Beginner's guide to writing comments?

Posted by Cameron on Programmers See other posts from Programmers or by Cameron
Published on 2011-11-14T04:47:41Z Indexed on 2011/11/14 10:11 UTC
Read the original article Hit count: 402

Filed under:

language-agnostic

|

comments

Is there a definitive guide to writing code comments, aimed at budding developers?

Ideally, it would cover when comments should (and should not) be used, and what comments should contain.

Do not comment WHAT you are doing, but WHY you are doing it.

The WHAT is taken care of by clean, readable and simple code with proper choice of variable names to support it. Comments show a higher level structure to the code that can't be (or is hard to) show by the code itself.

comes close, but it's a little concise for inexperienced programmers (an expansion on that with several examples and corner cases would be excellent, I think).

© Programmers or respective owner

Related posts about language-agnostic

Are there any language agnostic unit testing frameworks?

as seen on Programmers - Search for 'Programmers'
I have always been skeptical of rewriting working code - porting code is no exception to this. However, with the advent of TDD and automated testing it is much more reasonable to rewrite and refactor code. Does anyone know if there is a TDD tool that can be used for porting old code? Ideally you… >>> More
Language Agnostic Basic Programming Question

as seen on Stack Overflow - Search for 'Stack Overflow'
This is very basic question from programming point of view but as I am in learning phase, I thought I would better ask this question rather than having a misunderstanding or narrow knowledge about the topic. So do excuse me if somehow I mess it up. Question: Let's say I have class A,B,C and D… >>> More
Language-agnostic term for typed things that need memory

as seen on Stack Overflow - Search for 'Stack Overflow'
Is there an accepted general term that subsumes the concepts of variables, class instances and arrays? Basically "any typed thing that needs memory". In C++, such a thing is called an object, but I'm looking for a more language-agnostic term. § 1.8 The C++ object model 1 The constructs in… >>> More
Deprecated Methods in Code Base

as seen on Programmers - Search for 'Programmers'
A lot of the code I've been working on recently, both professionally (read: at work) and in other spheres (read: at home, for friends/family/etc, or NOT FOR WORK), has been worked on, redesigned and re-implemented several times - where possible/required. This has been in an effort to make things smaller… >>> More
Coding Competition, language agnostic guidelines?

as seen on Stack Overflow - Search for 'Stack Overflow'
Hi there: I might be doing a coding competition soon, I was wondering if anyone made one and what where the guidelines/ process. I'd like to make the competition appealing to all devs, and I m trying to come up with ideas as to how. the scenario is: There is an event running and we(of the coding… >>> More

Related posts about comments

SQL Developer Data Modeler: On Notes, Comments, and Comments in RDBMS

as seen on Oracle Blogs - Search for 'Oracle Blogs'
Ah the beautiful data model. They say a picture is worth a 1,000 words. And then we have our diagrams, how many words are they worth? Our friends from the Human Relations sample schema So our models describe how the data ‘works’ – whether that be at a logical-business level, or a… >>> More
Comments on Comments

as seen on Geeks with Blogs - Search for 'Geeks with Blogs'
I almost tweeted a reply to Capar Kleijne's question about comments on Twitter, but realized that my opinion exceeded 140 characters. The following is based upon my experience with extremes and approaches that I find useful in code comments. There are a couple extremes that I've seen and reasons… >>> More
Comments in string and strings in comments

as seen on Stack Overflow - Search for 'Stack Overflow'
Hi there, I am trying to count characters in comments included in C code using Python and Regex, but no success. I can erase strings first to get rid of comments in strings, but this will erase string in comments too and result will be bad ofc. Is there any chance to ask by using regex to not match… >>> More
checkins/recent not returning comments or even counts of comments

as seen on Stack Overflow - Search for 'Stack Overflow'
My application has been using the checkins/recent endpoint to show where all the current users friends are currently at and I had included a button the user could press to comment on a checkin. The button used to have the comment count on it until recently. It seems the checkins/recent endpoint no… >>> More
VS for Database Pros (GDR R2) Removes Sproc Comments (2 replies)

as seen on .NET 247 - Search for '.NET 247'
I have been working with my team to implement Data Dude GDR R2 for managing ALL of the databases for our applications. So far I am very pleased by what we can do with the tool with a single exception. I want to have a header with comments as part of every stored procedure so we can track the history… >>> More