Questions about writing comments in code.

learn more… | top users | synonyms

22
votes
21answers
7k 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: ...
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? ...
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 ...
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 ...
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 ...
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()); ...
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 ...
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 ...
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. ...
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 ...
3
votes
5answers
692 views

How should I handle exception that *should* never be thrown? [duplicate]

What is the best way to handle errors that shouldn't ever happen? My current way to do this is to throw an exception if the 'thing that shouldn't happen' does happen, like so: /* * Restoring from a ...
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 ...
159
votes
15answers
26k 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 ...
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 ...
60
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 ...
40
votes
14answers
6k 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 ...
29
votes
13answers
4k 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, ...
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
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 ...
1
vote
6answers
822 views

Working in a company that does not comment their code at all? [duplicate]

I work for a small software development house (10~ developers, a few product managers and a few support staff) that sells various products and services to organisations internationally through ...
10
votes
6answers
793 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 ...
8
votes
11answers
1k 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.
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
5answers
250 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 ...
0
votes
2answers
113 views

Is it a bad practice to cite URLs as references in comments? [closed]

Sometimes I think it's useful to cite a webpage (e.g. Stack Overflow questions) to justify and explain a piece of code. Is this considered bad practice?
-1
votes
3answers
338 views

Is it a good practice by commenting with owner name? [duplicate]

Possible Duplicate: How do you keep track of the authors of code? Here's several scenarios which may comment with owner name: bug fixing, i.e. // fixed bug 123 by xxx, solution is ... ... ...
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 ...
21
votes
9answers
17k 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 ...
56
votes
24answers
4k 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 ...
19
votes
13answers
1k 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 ...
8
votes
11answers
590 views

What should I put in comments while commiting to the Source Control?

I am a lone developer and maintain a SVN server for source control. So far, I haven't followed anything specific while committing my changes. I was just reviewing my previous commits, and couldn't ...
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 ...
11
votes
7answers
800 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 ...
0
votes
2answers
485 views

/*To Comment or Not To Comment…*/ [duplicate]

Possible Duplicates: Self Documenting Code Vs. Commented Code “Comments are a code smell” Best practices in comment writing and documentation Is commenting code useful, or just a ...
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 ...
8
votes
7answers
566 views

Commenting/In-Code Documentation Styles

This might be a stupid question, but it's been in the back of my head for a while and I can't find a decent answer anywhere else. I have a teacher who says we should explicitly list each parameter ...
3
votes
9answers
419 views

Do we need “obvious” Method Documentation information?

I know we have questions about comments in general but I'm specifically wondering about Java Doc style method documentation here. I've been pruning unnecessary comments as I refactor and I've ...
2
votes
2answers
262 views

How often are comments used in XML documents?

I'm currently developing a web-based XML managing program for a client (though I may 'market' it for future clients). Currently, it reads an XML document, converts it into manageable Javascript ...
0
votes
4answers
182 views

Emphasize Some Comments - but not Dirty the Code

I'm having trouble structuring my comments at the moment. I have major sections of the code that, when scrolling through the document, I want to be able to see those stand out. Examples: This is ...