How to capture personal or organizational programming best practices? - checkstyle

...or, what is the best practice for capturing best practices?
Note that I am not asking what these best practices are; these will vary from person to person, team to team, language to language, domain to domain.
To clarify, I am curious if there is anything approaching a standard for capturing coding best practices such as...
Example best practices
Naming conventions
Comment tags used
The holy war of curly brace positioning
Logging policies
Restrictions or emphasis on various design patterns
When to break out a separate function, file, or library
...and so on. Obviously this list can go on forever!
What do I mean by capturing?
I mean encoding these best practices in a way that is the most useful.
Keeping this information as so-called tribal knowledge is a weak form of capturing, in that it is prone to inconsistency and data loss, and is not easily enforced.
Maintaining checkstyle configuration is a strong form of capturing, in that it is very explicit and easily enforced. However, it is not very flexible and fails to capture higher-level thinking.
Solutions I am aware of
Amalgamate over classics like Clean Code or Code Complete, which is not customizeable or domain-specific,
Leverage tooling like checkstyle, which can't capture the nebulous, or
Create custom documentation.
Is there something better? Thank you!

Related

Scripting Language Design?

If I were to go to a dev. company and say "Please build me 'this' scripting language", are there any specific documents, and what types of documents that I should create, so they know exactly what I am wanting?
Any guidance is much appreciated.
Thank you
As Dave Swersky says, there are lots and lots of very well developed scripting languages already out there. Lua, for example, is very simple yet surprisingly powerful and has tiny yet efficient implementations.
But if you really, really want a scripting language custom built for you, then the nicest thing you could do for the implementor would be to provide him with a description of the language in Backus-Naur form. Ideally, that will allow them to create a scanner and parser for your language with very little effort. In addition, you will need to define your language's data types and how the map to the hardware's data types, and you will need to specify which library or built-in functions you want to provide, and how those will have effects in the outside world. The Lua Reference Manual is concise yet complete and defines that language and its library well. You'll want to come up with something comparable, or make do with a hand-waving simplification and hope your implementors invest their own brain power in filling the gaps left by your description.
It would help if you could offer some detail on why you would want to go to the time and expense to develop your own scripting language when there are at least three or four excellent options out there for free. If you have a targeted need for a language that does something specific, read up on Domain Specific Languages.

Whiteboard VS Real IDE Interview test

What in your opinion is a better way to test an applicant - have them write pseudo code on the whiteboard, or write specific code on the computer using Visual Studio?
In both cases questions concern manipulating some data structures. I know by myself that whiteboard can be more nerve wracking but could be good to see how the person acts under pressure.
It really depends on the applicant and the position they are applying for. If it is entry level, I'd say pseudo code on the board, that way you can test their logical thinking and not get caught up on language/framework specifics.
If you are looking for someone who is seasoned in a specific language, I'd probably vote for coding in their IDE of choice for that language. I'd also of course ask language specific questions.
I'm not too sure why you'd be very interested in seeing how someone codes under pressure. There are always of course deadlines and critical issues that can cause pressure, but unless your environment is always under pressure I'd question why you are really interested in that aspect.
I'd probably even go out on a limb and ask the applicant their preference on white board vs. IDE and have the exercise available in both formats.
My take is this.
What are you more interested in testing them on. Their ability to remember syntax and specific classes or their ability to break down a concept and communicate at a high level their approach to the solution?
If you are more interested in the former then use the IDE.
If you are more interested in the latter use the Whiteboard.
Granted most IDE's will do the mundane syntax checking and help you with references etc. But on a whiteboard I wouldn't be looking at this at all. I would be looking strictly for conceptual understanding
Just my 2c

Creative Terminology

I seem to use bland words such as node, property, children (etc) too often, and I fear that someone else would have difficulty understanding my code simply because the parts' names are vague, common words.
How do you find creative names for classes and components to make them more memorable?
I am particularly having trouble with generic tools which have no real description except their rather generic functional purpose. I would like to know if others have found creative ways to name things rather than simply naming them by their utility, such as AnonymousFunctionWrapperCallerExecutorFactory.
It's hard to answer. I find them just because they seem to 'fit'.
What I do know, however, is that I find it basically impossible to move on writing code unless something is named correctly, and it 'feels' good. If it isn't named right, I find it hard to use, and the code is generally confusing.
I'm not too concerned about something being 'memorable', only 'accurate'.
I have been known to sit around thinking out loud about what to name something. Take your time, and make sure you are really happy with the name. don't be afraid of using common/simple words.
I don't really have an answer, but three things for you to think about.
The late Phil Karlton famously said: "There are only two hard problems in computer science. Cache Invalidation and Naming Things." So, the fact that you are having trouble coming up with good names is entirely normal and even expected.
OTOH, having trouble naming things can also be a sign of bad design. (And yes, I am perfectly aware, that #1 and #2 contradict each other. Or maybe one should think of it more like balancing each other.) E.g., if a thing has too many responsibilities, it is pretty much impossible to come up with a good name. (Witness all the "Service", "Util", "Model" and "Manager" classes in bad OO designs. Here's an example Google Code Search for "ManagerFactoryFactory".)
Also, your names should map to the domain jargon used by subject matter experts. If you can't find a subject matter expert, that's a sign that you are currently worrying about code that you're not supposed to worry about. (Basically, code that implements your core business domain should be implemented and designed well, code in ancillary domains should be implemented and designed so-so, and all other code should not be implemented or designed at all, but bought from a vendor, where what you are buying is their core business domain. [Please interpret "buy" and "vendor" liberally. Community-developed Free Software is just fine.])
Regarding #3 above, you mentioned in another comment that you are currently working on implementing a tree data structure. Unless your company is in the business of selling tree data structures, that is not a part of your core domain. And the reason that you have trouble finding good names could be that you are working outside your core domain. Now, "selling tree data structures" may sound stupid, but there are actually companies that do that. For example, the BCL team inside Microsoft's developer division: they actually sell (well, for certain definitions of "sell", anyway) the .NET framework's Base Class Libraries, which include, among others, tree data structures. But note that for example Microsoft's C++ compiler team actually (literally) buys their STL from a third-party vendor – they figure that their core domain is writing compilers, and they leave the writing of libraries to a company who considers writing STLs their core domain. (And indeed, AFAIK, that company does nothing but write and sell STL implementations. That's their sole product.)
If, however, selling tree data structures is your core domain, then the names you listed are just fine. They are the names that subject matter experts (programmers, in this case) use when talking about the domain of tree data structures.
Using 'metaphors' is a common theme in agile (and pattern) literature.
'Children' (in your question) is an example of a metaphor that is extensively used and for good reasons.
So, I'd encourage the use of metaphors, provided they are applicable and not a stretch of the imagination.
Metaphors are everywhere in computing. From files to bugs to pointers to streams... you can't avoid them.
I believe that for the purpose of standardization and communication, it's good to use a common vocab, like in the same case for design patterns. I have a problem with a programmer who keeps 'inventing' his own terms and I have trouble understanding him. (He kept using the term 'events orchestrating' instead of 'scripting' or 'FCFS process'. Kudos for creativity though!)
Those common vocab describe stuff we are used to. A node is a point, somewhere in a graph, in a tree, or what-not. One way is to be specific to the domain. If we are doing a mapping problem, instead of 'node', we can use 'location'. That helps in a sense, at least for me. So I find there is a need to balance being able to communicate with other programmers, and at the same time keeping the descriptor specific enough to help me remember what it does.
I think node, children, and property are great names. I can already guess the following about your classes, just by their "bland" names:
Node - this class is part of a graph of objects
children - this variable holds a list of nodes belonging to the containing node.
I don't think "node" is either vague or common, and if you're coding a generic data structure, it's probably ok to have generic names! (With that being said, if you are coding up a tree, you could use something like TreeNode to emphasize that the node is part of a tree.) One way you can make the life of developers who will use your API easier is to follow the naming conventions of your platform's built in libraries. If everyone calls a node a node, and an iterator an iterator, it makes life easy.
Names that reflect the purpose of the class, method or property are more memorable than creative ones. Modern IDEs make it easier to use longer names so feel fee to be descriptive. Getting creative won't help as much as getting accurate.
I recommend to pick nouns from a specific application domain. E.g. if you are putting cars in a tree, call the node class Car - the fact that it is also a node should be apparent from the API. Also, don't try to be too generic in your implementation - don't put all attributes of the car into a hashtable named properties, but create separate attributes for make, color, etc.
A lot of languages and coding styles like to use all sorts of descriptive prefixes. In PHP there are no clear types, so this may help greatly. Instead of doing
$isAvailable = true;
try
$bool_isAvailable = true;
It is admittedly a pain, but usually well worth the time.
I also like to use long names to describe things. It may seem strange, but is usually easier to remember, especially when I go back to refactor my code
$leftNode->properties < $leftTreeNode->arrayOfNodeProperties;
And if all else fails. Why not fall back on a solid star wars themed program.
$luke->lightsaber($darth[$ewoks]);
And lastly, in college I named my classes after my professor, and then my class methods all the things I wanted to do to that jerk.
$Kube->canEat($myShorts, $withKetchup);

Can anybody give me an example of overused design patterns?

I've been hearing and reading about cases when people had come across cases of overused design patterns. Ok, missused design patterns are understandable phenomenon. What does it actually mean overused design patterns?
Do you have any examples and why do you think there are too many patterns?
The singleton is probably the most overused design pattern. I often see it used in many cases when it's out of scope and much more appropriate to directly instantiate objects.
After that, I believe the factory pattern is way overused as a shortcut of instantiating objects, many times without a real need.
Object Orientation, which is no longer a design pattern but a way of life. I have seen a lot of procedural code munged up in objects and a lot of objects for the sake of objects because the zeitgeist says "presumably you are object oriented", when a few lines of C and a struct would do just as well.
I cite it as the most over-ued design pattern because it is (probably) the most widely used design pattern and its merits are rarely questioned.
I vote for ActiveRecord.
Many popular data access frameworks use ActiveRecord as the only data access pattern, a sort of one-size-fits-all solution, even though Martin Fowler's book "Patterns of Enterprise Application Architecture" describes several other data access patterns, and details strengths of each pattern and how to decide when to use each pattern.
The (sometimes) so-called JavaBeans-Pattern: getters and setters for every field. Highly questionable and extremely widespread.
I guess Singleton gets easily overused (though it certainly has its legitime uses).
Addiction to the Singleton pattern is called Singletonitis. :) Symptoms include, at least, unnecessarily high coupling, and testing becoming more difficult.
Edit: As a prescribed cure for Singletonitis, you could try Inline Singleton, described in Refactoring to Patterns by Joshua Kerievsky.
Edit 2: For a good discussion on Singletons, see this older question: What is so bad about Singletons
PREAMBLE: Generally, Singleton is considered the most abused pattern, if for nothing more than the fact that many will use it to write in-line programming in fact, if not in actuality, while others use it as a substitute for global variables.
BODY:There is a book out there called, "A Pattern Language" which predates the illustrious GoF by several years. It calls for a similar language among different aspects of a project — it was apparently a major influence on "Design Patterns" and those who know both texts consider it superior.
My personal experience is that the GoF is only useful in certain circumstances, and a far cry from encompassing all of OOP. I actually find it quite amusing that several of the patterns are made obsolete in other languages, and others are merely redundantly describing the same scenario (Is there really that much difference between something which adapts and translates?)
Patterns, in general, are a good thing. It is good that Singletons generally use a static getInstance method. It is good that many MVC structures use similar naming conventions. On the other hand, Patterns are not everything and that needs to be remembered.
Recommended reading:
http://perl.plover.com/yak/design/
The singleton pattern, which is only suitable in a very few cases and makes testing harder. It's not only over-used, but it's often badly implemented in Java and C# - people often rush into double-checked locking when it's not only inappropriate but also relatively hard to get right.
EDIT: I really should have realised that everyone would post the same thing.
Next example, the factory pattern and in particular its use in the Java DOM API. Blech.
I would say the Singleton is well overused. There are often much better solutions than using what's essentially a global variable.
I'm going to weigh in on the much-overused Singleton. Quite often, developers learn only this one pattern and use it when a static class would be just as effective.
I think a worse problem than overused design patterns is patterns misapplied by enthusiastic developers who've recently learned a new pattern tool and decide they need to try it out. Recently I've been reading some of Misko Hevery's blog (http://misko.hevery.com/2008/08/17/singletons-are-pathological-liars/) entries on dependency injection. One of his major assertions is that the singleton pattern implemented as a global instance severely limits testability and should be avoided.
A few days ago I read an interesting opinion on patterns from Christian Gruber's blog. He suggests they are useful as a tool for discussing architectures, but shouldn't be used during design conception lest software architecture deteriorate into what he calls "paint by numbers." See the paragraph on Design Patterns: http://www.geekinasuit.com/2008/12/testability-re-discovering-what-we.html.
So possibly the issue with design patterns is misapplication and tunnel vision induced by the perception that all well designed software must fit into one of the patterns described in Gang of Four.
This was actually discussed by our one and only Jeff Atwood on Coding Horror:
http://www.codinghorror.com/blog/archives/000380.html
I keep seeing the Provider pattern used where there is only one provider. This seems like an awful lot of extra work with no benefit.
I too vote for Singleton: a global in abstracted clothing.
And Factory, since that makes it easier not to think about how objects are connected together in a given program.

Do you use design patterns?

What's the penetration of design patterns in the real world? Do you use them in your day to day job - discussing how and where to apply them with your coworkers - or do they remain more of an academic concept?
Do they actually provide actual value to your job? Or are they just something that people talk about to sound smart?
Note: For the purpose of this question ignore 'simple' design patterns like Singleton. I'm talking about designing your code so you can take advantage of Model View Controller, etc.
Any large program that is well written will use design patterns, even if they aren't named or recognized as such. That's what design patterns are, designs that repeatedly and naturally occur. If you're interfacing with an ugly API, you'll likely find yourself implementing a Facade to clean it up. If you've got messaging between components that you need to decouple, you may find yourself using Observer. If you've got several interchangeable algorithms, you might end up using Strategy.
It's worth knowing the design patterns because you're more likely to recognize them and then converge on a clean solution more quickly. However, even if you don't know them at all, you'll end up creating them eventually (if you are a decent programmer).
And of course, if you are using a modern language, you'll probably be forced to use them for some things, because they're baked into the standard libraries.
In my opinion, the question: "Do you use design pattern?", alone is a little flawed because the answer is universally YES.
Let me explain, we, programmers and designers, all use design patterns... we just don't always realise it. I know this sounds cliché, but you don't go to patterns, patterns come to you. You design stuff, it might look like an existing pattern, you name it that way so everyone understand what you are talking about and the rationale behind your design decision is stronger, knowing it has been discussed ad nauseum before.
I personally use patterns as a communication tool. That's it. They are not design solutions, they are not best practices, they are not tools in a toolbox.
Don't get me wrong, if you are a beginner, books on patterns will show you how a solution is best solved "using" their patterns rather than another flawed design. You will probably learn from the exercise. However, you have to realise that this doesn't mean that every situation needs a corresponding pattern to solve it. Every situation has a quirk here and there that will require you to think about alternatives and take a difficult decision with no perfect answer. That's design.
Anti-pattern however are on a totally different class. You actually want to actively avoid anti-patterns. That's why the name anti-pattern is so controversial.
To get back to your original question:
"Do I use design patterns?", Yes!
"Do I actively lean toward design patterns?", No.
Yes. Design patterns can be wonderful when used appropriately. As you mentioned, I am now using Model-View-Controller (MVC) for all of my web projects. It is a very common pattern in the web space which makes server-side code much cleaner and well-organized.
Beyond that, here are some other patterns that may be useful:
MVVM (Model-View-ViewModel): a similar pattern to MVC; used for WPF and Silverlight applications.
Composition: Great for when you need to use a hierarchy of objects.
Singleton: More elegant than using globals for storing items that truly need a single instance. As you mentioned, a simple pattern but it does have its uses.
It is worth noting a design pattern can also highlight a lack of language features and/or deficiencies in a language. For example, iterators are now built in as part of newer languages.
In general design patterns are quite useful but you should not use them everywhere; just where they are a good fit for your needs.
I try to, yes. They do indeed help maintainability and readability of your code. However, there are people who do abuse them, usually (from what I've seen) by forcing a system into a pattern that doesn't exist.
I try to use patterns if they are applicable. I think it's kind of sad seeing developers implement design patterns in code just for the sake of it. For the right task though, design patterns can be very useful and powerful.
There are many design patterns beyond the simple that are used in "real world". Good example Stackoverflow uses the Model View Controller Pattern. I have used Class Factories multiple times in projects for my employer, and I have seen many already written projects using them as well.
I am not saying every design pattern is being used but many are.
Yes we do, it usually happens when we start designing something and then someone notices that it resembles an existing pattern. We then take a look at it and see how it would help us achieve our goal.
We also use patterns that are not documented but that emerge from designing a lot.
Mind you, we don't use them a lot.
Yes, Factory, Chain of Responsibility, Command, Proxy, Visitor, and Observer, among others, are in use in a codebase I work with daily. As far as MVC goes, this site seems to use it quite well, and the devs couldn't say enough good things in the latest podcast.
Yes, I use a lot of well known design patterns, but I also end up building some software that I later find out uses a 'named' design pattern. Most elegant, reusable designs could be called a 'pattern'. It's a lot like dance moves. We all know the waltz, and the 2-step, but not everyone has a name for the 'bump and scoot' although most of us do it.
MVC is very well known so yes we use design patterns quite a lot. Now if your asking about the Gang of Four patterns, there are several that I use because other maintainers will know the design and what we are working towards in the code. There are several though that remain fairly obscure for what we do, so if I use one I don't get the full benefits of using a pattern.
Are they important, yes because it gives you a method of talking about software design in a quick efficient and generally accepted way. Can you do better custom solutions, well yes (sorta)?
The original GoF patterns were pulled from production code, so they catalogued what was already being used in the wild. They aren't purely or even mostly an academic thing.
I find the MVC pattern really useful to isolate your model logic, which can than be reused or worked on without too much trouble. It also helps de-coupling your classes and makes unit testing easier. I wrote about it recently (yes, shameless plug here...)
Also, I've recently used a factory pattern from a base class to generate and return the proper DataContext class that I needed on the fly, using LINQ.
Bridges are used when trying when trying to glue together two different technologies (like Cocoa and Ruby on the Mac, for example)
I find, however, that whenever I implement a pattern, it's because I knew about it before hand. Some extra thought generally goes into it as I find I must modify the original pattern slightly to accommodate my needs.
You just need to be careful not to become and architecture astronaut!
Yes, design patterns are largely used in the real world - and daily by many of the people I work with.
In my opinion the biggest value provided by design patterns is that they provide a universal, high level language for you to convey software design to other programmers.
For instance instead of describing your new class as a "utility that creates one of several other classes based on some combination of input criteria", you can simply say it's an "abstract factory" and everyone instantly understands what you're talking about.
Yes, design patterns or abstractly patterns are part of my life, where I look, I begin to see them. Therefore, I am surrounded by them. But, as you know, little knowledge is a dangerous thing. Therefore, I strongly recommend you to read GoF book.
One of the main problems about design patterns, most developers just do not get the idea, or do not believe in them. And most of the time they argue about the variables, loops, or switches. But, I strongly believe that if you do not speak the pattern language, your software will not go far and you will find yourselves in a maintenance nightmare.
As you know, anti-pattern is also dangerous thing and it happens when you have little expertise on design patterns. And refactoring anti-patterns is much more harder. As a recommended book about this problem please read "AntiPatterns: Refactoring Software, Architectures, and Projects in Crisis".
Yes.
We are even using them in my current job: Mainframe coding with COBOL and PL/I.
So far I have seen Adaptor, Visitor, Facade, Module, Observer and something very close to Composite and Iterator. Due to the nature of the languages it's mostly strutural patterns that are used. Also, I'm not always sure that the people who use them do so conciously :D
I absolutely use design patterns. At this point I take MVC for granted as a design pattern. My primary reason for using them is that I am humble enough to know that I am likely not the first person to encounter a particular problem. I rarely start a piece of code knowing which pattern I am going to use; I constantly watch the code to see if it naturally develops into an existing pattern.
I am also very fond of Martin Fowler's Patterns of Enterprise Application Architecture. When a problem or task presents itself, I flip to related section (it's mostly a reference book) and read a few overviews of the patterns. Once I have a better idea of the general problem and the existing solutions, I begin to see the long term path my code will likely take via the experience of others. I end up making much better decisions.
Design patterns definitely play a big role in all of my "for the future" ideas.