Questions about writing comments in code.
139
votes
23answers
11k 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 ...
70
votes
22answers
3k 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 ...
54
votes
24answers
3k views
Is writing comments inside methods not a good practice?
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 ...
52
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
...
48
votes
13answers
6k 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());
...
48
votes
16answers
3k views
Do TODO comments make sense?
I am working an 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 ...
37
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 ...
36
votes
14answers
3k 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 ...
35
votes
12answers
1k 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 ...
25
votes
17answers
2k views
Why would 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 ...
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 ...
24
votes
18answers
1k views
What is your typical source control commit comment? [closed]
What details, if any, do you record in your comments when committing to source control? Do you tend to commit every tiny change or only mega updates to your code? Do you have any system or style guide ...
24
votes
13answers
2k views
Is commented out code really always bad?
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, ...
23
votes
20answers
3k 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:
...
21
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 ...
20
votes
8answers
1k views
Should comments say WHY the program is doing what it is doing? (opinion on a dictum by the inventor of Forth)
The often provocative Chuck Moore (inventor of the Forth language) gave the following advice (paraphrasing):
"Use comments sparingly. Programs are self-documenting, with a
modicum of help from ...
20
votes
5answers
903 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
“// …” 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
10answers
1k views
Are chatty/humorous comments in source code acceptable or unprofessional? [duplicate]
Possible Duplicate:
Humor in Documentation
Throughout my professional career, I have often relied on chatty or humorous comments in source code (or source control commit messages) to help ...
16
votes
12answers
10k views
What does XXX mean in a comment?
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 ...
16
votes
13answers
1k views
Comment before or after the relevant code
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 ...
16
votes
9answers
1k 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? ...
16
votes
8answers
947 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 ...
14
votes
11answers
521 views
Please share experience on how to make the source code easy for other to follow?
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 ...
14
votes
4answers
529 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
3answers
7k 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?
13
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 ...
13
votes
11answers
725 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 ...
13
votes
15answers
699 views
Does anyone put comments in HTML anymore? [closed]
At least in my experience, most of my web applications are not static web pages but dynamic from a scripting engine.
Just curious, does anyone use HTML comments aside from for IE fixes anymore?
13
votes
2answers
613 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
4answers
482 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
6answers
2k 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 ...
12
votes
7answers
891 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 ...
12
votes
8answers
1k 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
543 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
5answers
203 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
9answers
910 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 ...
10
votes
7answers
748 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 ...
10
votes
6answers
414 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.
...
10
votes
6answers
642 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 -->
...
9
votes
6answers
691 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 ...
9
votes
11answers
506 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 ...
9
votes
7answers
507 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 ...
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.
8
votes
7answers
687 views
Use of NotImplementedException
Is it considered bad practice to throw NotImplementedException for code you haven't written yet? Possibly TODO comments would be considered safer?
8
votes
7answers
436 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 ...
8
votes
8answers
359 views
Does commentary style affect how readers understand code?
This question has been obsessing me for the past 2 months.
A while ago a friend who is a great programmer gave me some example codes, and for the first time I've noticed a unique style of organizing ...
8
votes
4answers
387 views
Annotate source code with diagrams as comments
I write a lot of (primarily c++ and javascript) code that touches upon computational geometry and graphics and those kinds of topics, so I have found that visual diagrams have been an indispensable ...
8
votes
5answers
271 views
Should a method comment include both a summary and return description when they're often so similar?
I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.
I like to follow the rule of adding XML comments for ...
7
votes
9answers
635 views
What are your thoughts on Periods/Full Stops in code comments?
I saw this asked in the SO Tavern, so I'm posting the question here. I thought it an interesting question. (Of course it doesn't belong on SO, but I think it's OK here.)
Do you add periods (or, as ...
