Code Comments

Who would have ever thought that people would think comments are a bad thing?  That is the opinion that you get about comments; actually, Martin Fowler said that comments aren't bad; however, if the comments are explaining what your code is doing, without your code being readable enough to handle it's own, it's time for a refactoring.  Comments can be a great way to prototype changes, or to think out your design as well, as Steve McConnell said in Code Complete.  He further said to leave in the comments, even though they will be very verbose.  You will see in my code, that I usually follow this approach.

Whether that is right or wrong, your code should be readable and understandable.  With custom objects, especially framework or third-party components, that can't always be the case, but it should be as readable and understandable as possible.  I still employ comments, and though your code should be readable throughout, I still do it.


# re: Code Comments

Monday, October 30, 2006 5:51 PM by dsmyth

Hi, I just walked into a new job where their project was 3 million lines of badly designed uncommented code. They're philosophy was write self-documenting code as comments are timely to maintain.

I couldn't believe it, code should be commented!! How and what you comment is important but you just need to comment. I'm with you 100%.

They also didn't draw UML or database diagrams. Everything was kept in the heads of the developers.