Describe Concepts in Comments!

It’s common knowledge that commenting your code is a must.
But that’s where the wrong interpretations come. “// incrementing i” above “i++” is one extreme example of useless comments, but what can be often observed is “shallow commenting” – i.e. comments describing what exactly is done, but not why. In other words programmers may forget to document the concepts and ideas behind the code.
For example, imagine you see ClientDocumentIndexer and DocumentIndexer. What’s the difference? The code may have comments explaning what happens when sending the documents to the search engine, but there is nothing about the difference between the two. Same goes for things like DownloadRecord and DownloadLog. And for millions of examples throughout thousands of codebases. The comments in these classes fail to communicate their business purpose. Then there is the FooListenerBuilderFactory – yes, I know all these patterns, but it still doesn’t make sense without an explanation why each of them is required.
Sometimes there is sufficient explanation about these concepts in some intranet document. There’s just no link between the code and the description. Adding a link will most likely be sufficient for the reader to understand what’s the purpose of a given class or method.
What if there is no spec/document? Then you’d have to write that “document” in the code. Don’t be verbose – just outline the reason for the class existence, and how it fits into the program flow. Each piece of code should make sense to someone that is not familiar with all the business requirements.
Sounding obvious? Well, if it was, you wouldn’t be seeing code that is hard to understand out of context.
To summarize:

• document the concepts and ideas of a class, not (just) how it functions internally
• if relevant, explain the reason for a class existence and how it differs from similar classes
• document the context of a class – how it fits into the program flow
• link requirements documents, if such exist

How to Handle Project Configuration

Every web project needs some environment-specific configurations. Database credentials, root url, smtp settings, to name a few. It’s a recurring question on stackoverflow, and I’ve seen a lot of variations on the topic, and here I’ll describe the one that I think is best.

• put all such properties in a .properties file (for example application.properties)
• have that application.properties sitting outside the web application. It is not bundled with the build
• provide a command-line option that indicates where that file is located. For example -Dconfig.location=/home/you/config
• on application startup (in a ServletContextListener usually) load the file and put it in a map. Can be java.util.Properties or a HashMap
• for spring users – use <context:property-placeholder-configurer location="file://${config.location}/application.properties" . Other frameworks will likely have some mechanism for loading such global properties
• hold a skeleton properties file in the SCM repository. It should contain all properties, but their values are irrelevant – they will change on each environment
• the ops team is likely to benefit from versioning different environment configurations (production, qa, stage), so a separate /config folder/subproject can be created and all environment-specific properties can be stored there. When adding a property developers should go and update all files accordingly
• properties that are not dependent on the environment, but are still global for the project, can be stored within the project (src/main/resources for maven), and committed to SCM. They can be merged with the external properties on startup (merged in memory, that is)
• most of the externalizable properties can have reasonable defaults – the smtp server of the company, the database driver, etc. They can be placed in a application-defeault.properties within the project, and the external file can override them. This is just an option – if you are going to have a file committed in the repository with those reasonable defaults, and each environment to use that file as a basis, it’s virtually the same

Developers can easily run their projects that way. Ops can easily deploy builds on different environments. The build remains environment-agnostic.