Questions about writing comments in code.

learn more… | top users | synonyms

162
votes
15answers
27k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
161
votes
23answers
14k views

How can I deal with a team member who dislikes making comments in code?

One of my team members consistently avoids making comments in his code. His code is not self-documenting, and other programmers have a difficult time understanding his code. I have asked him ...
74
votes
22answers
4k views

How do I convince my fellow devs to WANT to add comments to source code commits?

I know that Subversion (what we're using at work) can be configured to require comments on commits, however I'm not in a position of power to simply turn this on. I know that my reason for commenting ...
70
votes
13answers
4k views

What are examples of comments that tell you why instead of how or what? [closed]

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about ...
61
votes
16answers
6k views

Do TODO comments make sense?

I am working on a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this ...
60
votes
13answers
8k views

Can commented-out code be valuable documentation?

I wrote the following code: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); ...
56
votes
24answers
5k views

Is writing comments inside methods not a good practice? [duplicate]

A friend told me that writing comments inside methods is not good. He said that we should have comments only for the method definitions(javadocs) but not inside the method body. It seems he read in a ...
54
votes
17answers
3k views

Are first person comments distracting and unprofessional?

I just found myself writing the following comment in some (archaic Visual Basic 6.0) code I was writing: If WindowState <> 1 Then 'The form's not minimized, so we can resize it safely ...
45
votes
19answers
3k views

Forcing people to read and understand code instead of using comments, function summaries and debuggers? [duplicate]

I am a young programmer (finished computer science university but still under a year of working in the industry) and I recently got a job working on some C code for a decent size web service. Looking ...
40
votes
9answers
2k views

Code maintenance: To add comments in code or to just leave it to the version control?

We have been asked to add comments with start tags, end tags, description, solution etc for each change that we make to the code as part of fixing a bug / implementing a CR. My concern is, does this ...
40
votes
14answers
7k views

Why are /// comment blocks important?

Someone once said we should prefix all our methods with the /// <summary> comment blocks (C#) and I am wondering if that is true or not. I started to use them and found they annoyed me quite a ...
37
votes
16answers
6k views

Good idea to put bug numbers in a comment in the beginning of the source file? [closed]

Is it a good practice to put bug numbers in the file itself inside a header comment? The comments would look something like this: MODIFIED (MM/DD/YY) abc 01/21/14 - Bug 17452317 - npe in drill ...
34
votes
12answers
2k views

Are outdated comments an urban myth?

I constantly see people making the claim that "comments tend to become outdated." The thing is, I think I have seen maybe two or three outdated comments my entire career. Outdated information in ...
29
votes
13answers
5k views

Is commented out code really always bad? [duplicate]

Practically every text on code quality I've read agrees that commented out code is a bad thing. The usual example is that someone changed a line of code and left the old line there as a comment, ...
28
votes
18answers
3k views

Why would a company develop an atmosphere which discourage code comments?

I was taught in university to write comments for our programs. As I write comments, I feel like I have a better organization and understand the programs better. However, I am in a company where most ...
27
votes
8answers
1k views

good replacement for commenting out code? [duplicate]

It bothers me to see commented out code and it seems often-times a symptom of developers not being proficient in advanced source control features, but on the other hand source control does not really ...
25
votes
7answers
1k views

Should one comment differently in functional languages?

I'm just getting started with functional programming and I'm wondering about the correct way to comment my code. It seems a little redundant to comment a short function as the names and signature ...
23
votes
5answers
1k views

Beginner's guide to writing 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. This ...
23
votes
3answers
17k views

What javadoc equivalents do you use in .net? [closed]

Java developers use Javadoc in order to write inline documentation in their comments. What are the alternatives for .net - specifically c# and VB.net that people actually use in real world projects?
22
votes
21answers
8k views

Self Documenting Code Vs. Commented Code

I had a search but didn't find what I was looking for, please feel free to link me if this question has already being asked. Earlier this month this post was made: ...
22
votes
9answers
18k views

What does XXX mean in a comment? [closed]

What do people generally mean whenever you see XXX in a comment. Occasionally, I'll see a comment like this: # XXX - This widget really should frobulate the whatsit Of course, I can tell what the ...
22
votes
8answers
2k views

Should comments say WHY the program is doing what it is doing? (opinion on a dictum by the inventor of Forth) [duplicate]

The often provocative Chuck Moore (inventor of the Forth language) gave the following advice[1]: Use comments sparingly! (I bet that's welcome.) Remember that program you looked through - the ...
22
votes
13answers
2k views

When do you start documenting the code?

Some friends and I recently started a medium-size project. We already covered the design part (at least the first attempt) and now we are moving into coding. We already have implemented some objects ...
19
votes
13answers
2k views

Comment before or after the relevant code [closed]

Assuming a comment won't fit (or can't go) on the line it applies to, should one write the comment before the code or after? Well, wherever future readers will best understand the comment's scope. In ...
19
votes
9answers
4k views

Style and recommendations of commenting code

I want to hear from you any advice and experience of writing comments in your code. How do you write them in the most easy and informative way? What habits do you have when commenting parts of code? ...
17
votes
12answers
2k views

Correct comment to put for boolean function arguments that are “false”?

From some open source projects, I gathered the following coding style void someFunction(bool forget); void ourFunction() { someFunction(false /* forget */); } I always have doubt about what ...
17
votes
11answers
1k views

Why are we supposed to use short functions to sectionalize our code? [duplicate]

I've seen an increasing trend in the programming world saying that it is good practice to separate code blocks into their own functions. Obviously, if that code block is reusable, you should do that. ...
17
votes
11answers
1k views

“// …” comments at end of code block after } - good or bad?

I've often seen such comments be used: function foo() { ... } // foo while (...) { ... } // while if (...) { ... } // if and sometimes even as far as if (condition) { ... } // if ...
17
votes
3answers
3k views

How to solve the problem of nested comments

It appears in not just one language that comments can't be nested. Do you have a good solution for this problem? One workaround in C/C++ and Java is to only use the single-line comment but it becomes ...
17
votes
8answers
1k views

Are 'edited by' inline comments the norm in shops which use revision control?

The senior dev in our shop insists that whenever code is modified, the programmer responsible should add an inline comment stating what he did. These comments usually look like // YYYY-MM-DD <User ...
16
votes
4answers
2k views

Is the “Gets or sets ..” necessary in XML documentation of properties?

I am looking for a recommendation of a best practice for XML comments in C#. When you create a property, it seems like that the expected XML documentation has the following form: /// <summary> ...
14
votes
16answers
2k views

Would a language which doesn't allow comments yield more readable code? [closed]

Just out of curiosity, I started wondering whether a language which doesn't allow comments would yield more readable code as you would have be forced to write self-commenting code. Then again, you ...
14
votes
11answers
837 views

Is it efficient to attach a comment on every function?

I moved to this company recently, and my first reaction of the development process leaves me with doubts. Here is where I really doubt the efficiency: Every single function must have Javadoc style ...
14
votes
6answers
3k views

Best practices in comment writing and documentation

Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even ...
13
votes
7answers
1k views

Why don't more languages support recursive/nested comments? [duplicate]

Possible Duplicate: Why do most programming languages not nest block comments? Most languages I've worked with don't have support for recursive/nested comments. Is there any reason why ...
13
votes
2answers
1k views

What is the best approach for inline code comments?

We are doing some refactoring to a 20 years old legacy codebase, and I'm having a discussion with my colleague about the comments format in the code (plsql, java). There is no a default format for ...
13
votes
9answers
557 views

Please share experience on how to make the source code easy for other to follow? [closed]

I can write source code in a period of time, but after a while of not touching the project, it takes me time to be familiar with the source code again. Also, other people need some time to study the ...
12
votes
6answers
480 views

Is it good practice to comment with issue number?

I saw many issue numbers from comments of jQuery code(Actually, there were 69 issue numbers in jQuery code). I think it would be good practice, but I've never seen any guidelines of this practice. ...
12
votes
4answers
723 views

Is there justification for leaving conflict markers in checked-in code?

Consider conflict markers. i.e.: <<<<<<< branch blah blah this ======= blah blah that >>>>>>> HEAD In the particular case which has motivated me to post ...
12
votes
8answers
2k views

Why do most programming languages not nest block comments?

A few do, but not any of the popular ones as far as I know. Is there something bad about nesting comments? I plan to have block comments nest in the (small) language I'm working on, but I would like ...
12
votes
4answers
698 views

Co-worker uses ridiculous commenting convention, how to cope? [closed]

A co-worker in the small start-up I work at writes (C++) code like this: // some class class SomeClass { // c'tor SomeClass(); // d'tor ~SomeClass(); // some function void ...
11
votes
9answers
1k views

What is a good way to comment if-else-clauses? [closed]

Whenever I'm writing a typical if-else-construct in any language I wonder what would be the best way (in terms of readability and overview) to add comments to it. Especially when commenting the else ...
11
votes
7answers
804 views

Are More Comments Better in High-Turnover Environments?

I was talking with a colleague today. We work on code for two different projects. In my case, I'm the only person working on my code; in her case, multiple people work on the same codebase, including ...
11
votes
5answers
253 views

Is it OK to put a link to Q&A sites in a program's comments?

In quite some codebase you can see comments stating things like: // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade) So I've got a few questions, but they're all related. Is it ...
10
votes
6answers
800 views

Are comments considered a form of documentation?

When I am writing small scripts for myself, I stack my code high with comments (sometimes I comment more than I code). A lot of people I talk to say that I should be documenting these scripts, even ...
10
votes
6answers
770 views

<!— open --> Why do so many developers do this in their HTML? <!— /close -->

<body> <!-- wrapper --> <div id="wrapper"> <!-- title --> <div id="title"><img src="title.png" alt="" /></div> <!-- form wrapper --> ...
10
votes
7answers
646 views

Writing documentation for well understood methods like equals in Java

Is it a good practice to write comments for widely known methods like equals, compareTo etc? Consider the below code. /** * This method compares the equality of the current object with the ...
10
votes
2answers
370 views

Is spreading code with refactoring comments a good idea?

I am working on a "spaghetti-code" project, and while I am fixing bugs and implementing new features, I also do some refactoring in order to make the code unit-testable. The code is often so tightly ...
8
votes
11answers
2k views

Version control comments - past or present tense

For version control comments what do other users do/recommend - past or present tense? I.e. Changed x to be y. or Changing x to be y.
8
votes
6answers
2k views

Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...