Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.Comments are not like Schindler's List. They are not "pure good." Indeed, comments are, at best, a necessary evil. If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much, perhaps not at all.

Write Better Comments Part 1.

It is sometimes useful to provide basic information with a comment. For example, consider this comment that explains the return value of an abstract method:/ Returns an instance of the Responder being tested. protected abstract Responder responderInstance ();A comment like this can sometimes be useful, but it is better to use the name of the function to convey the information where possible. For example, in this case the comment could be made redundant by renaming the function: responderBeingTested.Here's a case that's a bit better:// format matched kk:mm:ss EBE, MMM dd, yyyy

Informative Comments (1)

This subtle bit of misinformation, couched in a comment that is harder to read than the body of the code, could cause another programmer to blithely call this function in the expectation that it will return as soon as this .closed becomes true. That poor programmer would then find himself in a debugging session trying to figure out why his code executed so slowly.

Misleading Comments (2)

Nowadays, most good IDEs provide special gestures and features to locate all the TODO comments, so it's not likely that they will get lost. Still, you don't want your code to be littered with TODOs. So scan through them regularly and eliminate the ones you can.

TODO Comments (2)

Some comments are necessary or beneficial. We'll look at a few that I consider worthy of the bits they consume. Keep in mind, however, that the only truly good comment is the comment you found a way not to write.

Good Comments

Most comments fall into this category. Usually they are crutches or excuses for poor code or justifications for insufficient decisions, amounting to little more than the programmer talking to himself.

Bad Comments

Sometimes our corporate coding standards force us to write certain comments for legal reasons. For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.Here, for example, is the standard comment header that we put at the beginning of every source file in FitNesse. I am happy to say that our IDE hides this comment from acting as clutter by automatically collapsing it./ Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.

Legal Comments

Pattern timeMatcher = Pattern. compile ("'|d*: 11d*: 1 1d* Ww*, Ww* Nd*, lId* n) :In this case the comment lets us know that the regular expression is intended to match a time and date that were formatted with the SimpleDateFormat. format function using the specified format string. Still, it might have been better, and clearer, if this code had been moved to a special class that converted the formats of dates and times. Then the comment would likely have been superfluous.

Informative Comments (2)

TODOS are jobs that the programmer thinks should be done, but for some reason can't do at the moment. It might be a reminder to delete a deprecated feature or a plea for someone else to look at a problem. It might be a request for someone else to think of a better name or a reminder to make a change that is dependent on a planned event. Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

TODO Comments (1)

Sometimes, with all the best intentions, a programmer makes a statement in his comments that isn't precise enough to be accurate. Consider for another moment the badly redundant but also subtly misleading comment we saw in Listing 4-1.Did you discover how the comment was misleading? The method does not return when this.closed becomes true. It returns if this.closed is true; otherwise, it waits for a blind time-out and then throws an exception if this closed is still not true.

Misleading Comments

Learning to write clean and descriptive comments inside your code requires skill, but you should avoid it! Learn how important (or not) are comments within your code through the first part of the clean code book

Looks at the principles and clean code, includes case studies showcasing the practices of writing clean code, and contains a list of heuristics and "smells" accumulated from the process of writing clean code.

books

Books

computerscience

Computer Science

Even bad code can function. But if code isn't clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn't have to be that way. Noted software expert Robert C. Martin presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship. Martin has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code "on the fly" into a book that will instill within you the values of a software craftsman and make you a better programmer--but only if you work at it. What kind of work will you be doing? You'll be reading code--lots of code. And you will be challenged to think about what's right about that code, and what's wrong with it. More importantly, you will be challenged to reassess your professional values and your commitment to your craft. Clean Code is divided into three parts. The first describes the principles, patterns, and practices of writing clean code. The second part consists of several case studies of increasing complexity. Each case study is an exercise in cleaning up code--of transforming a code base that has some problems into one that is sound and efficient. The third part is the payoff: a single chapter containing a list of heuristics and "smells" gathered while creating the case studies. The result is a knowledge base that describes the way we think when we write, read, and clean code. Readers will come away from this book understanding <ul> <li>How to tell the difference between good and bad code</li> <li>How to write good code and how to transform bad code into good code</li> <li>How to create good names, good functions, good objects, and good classes</li> <li>How to format code for maximum readability</li> <li>How to implement complete error handling without obscuring code logic</li> <li>How to unit test and practice test-driven development</li> </ul> This book is a must for any developer, software engineer, project manager, team lead, or systems analyst with an interest in producing better code.

Robert Cecil Martin, commonly called Uncle Bob, is a software engineer, advocate of Agile development methods, and President of Object Mentor Inc. Martin and his team of software consultants use Object-Oriented Design, Patterns, UML, Agile Methodologies, and eXtreme Programming with worldwide clients.He was Editor in Chief of the C++ Report from 1996 to 1999. He is a featured speaker at international conferences and trade shows.

TODO Comments (1)

Similar ideas to TODO Comments (1)

Explain unidiomatic code in comments

Use comments to mark incomplete implementations

Awkward conversations