Programming Practices – Issues with Comments Explaining Complex Code

Javadoc (and, in the Microsoft word, XMLDoc) annotations are not comments, they are documentation.

Comments can be as sparse as you want them to be; assuming your code is halfway readable, then ordinary comments are merely signposts to aid future developers in understanding/maintaining the code that they've already been staring at for two hours.

The documentation represents a contract between a unit of code and its callers. It is part of the public API. Always assume that Javadoc/XMLdoc will end up either in a help file or in an autocomplete/intellisense/code-completion popup, and be observed by people who are not examining the internals of your code but merely wish to use it for some purpose of their own.

Argument/parameter names are never self-explanatory. You always think they are when you've spent the past day working on the code, but try coming back to it after a 2-week vacation and you'll see just how unhelpful they really are.

Don't misunderstand me - it's important to choose meaningful names for variables and arguments. But that is a code concern, not a documentation concern. Don't take the phrase "self-documenting" too literally; that is meant in the context of internal documentation (comments), not external documentation (contracts).

This question is really two questions in one.

Todo comments

Of all the ways to track action items, this is the worst. TODO comments are good during active work or as a way of suggestion to a maintainer, "here is something that could maybe be improved on in the future". But if you rely on TODO comments for getting work done, you're doomed to fail.

What to do about it

TODO comments are basically technical debt, so they should be handled like any other technical debt. Either tackle them right away, if you have time, or put them in the backlog so they can be tracked and prioritized.

Generally speaking, and this is totally opinionated and open for debate, TODO comments could be considered a code smell. If a TODO comment makes it as far as being checked into version control, you have to ask yourself, are you actually going to follow through on it right now? If not, that's ok. Just be honest with yourself and put it in the backlog.

How you manage this backlog comes down to business process, company politics, and perhaps some personal autonomy. But you still need a tracked and prioritized backlog to make sure it happens.

Database changes

Yes, database changes are tricky with a zero-downtime policy. Some tricks to help make it less painful:

Post-deploy process

Create a post-deploy process that runs as part of the same release. However you want it to work. On the last system I worked on, I designed a 4-phase deployment:

1. preapp database scripts
2. web apps
3. postapp database scripts
4. maintenance window database scripts

The idea was that wherever possible, we would put as much of the database changes into preapp as possible.

Postapp was reserved for the unusual cases where we needed to make incompatible schema changes. In those cases, preapp would make enough of a change to make the new application code compatible (maybe creating a temporary view for compatibility), and postapp would cleanup any such temporary artifacts.

Maintenance window phase was reserved for changes which truly required downtime or where the risk or cost of a live deployment was not worth it. For example, scripts that change massive amounts of data may need to lock an entire table.

Deploy frequently

If you deploy new releases frequently enough, you can reach a point where carrying a change across 2 or 3 releases is trivial. Long release cycles amplify the cost of database changes.