Eliminate Useless Comments

Be careful what you ask for.   I was reviewing some code that had absolutely no comments. I asked the developer to add some comment.   So, indeed they did, however the comments added no value to the code at all.   There is no point in adding comments for comments’ sake.  In fact, useless comments make the code worse by adding lines without adding value.   Let’s talk about what a valuable comment is.

 

Content Free Documentation

I was trying to use an open source tool, and reading the documentation, I was frustrated by more content free documentation.  Here is the example.

 

LaTeX: What I wish I had known, Part 1

I do a lot of writing, and I switched recently from a variety of word processors etc. to LaTeX. It is free, well supported, and does a great job of typesetting books. But for a normal business user with a normal experience in WYSIWYG word processors there are some big surprises. Here is what I wish I knew before starting that journey.

 

The Error Message IS the Documentation

Another example of content free documentation below: documentation that is a waste of screen space even to display it on the screen.  Here the issue is a development team so enamored with Documentation (with a capital D) that they really want to do a complete job to document everything, that they are blind to a better approach.  The real goal of any software development should be to eliminate the need for documentation in the first place.