RSS

Tag Archives: documentation

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. Read the rest of this entry »

 
Leave a comment

Posted by on October 18, 2019 in Coding, practice

 

Tags: , , , ,

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. Read the rest of this entry »

 
Leave a comment

Posted by on January 9, 2015 in Coding

 

Tags:

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. Read the rest of this entry »

 
Leave a comment

Posted by on July 26, 2014 in LaTeX

 

Tags: ,

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. Read the rest of this entry »

 
Leave a comment

Posted by on March 28, 2012 in Design

 

Tags: ,