Questions about writing comments in code.

learn more… | top users | synonyms

1
vote
1answer
610 views

instantiate or initialize when using a new class?

my question is rather a matter of English language. For proper commenting my code I want to know when you do for example the following code, what comment you can write for it? public class TestClass ...
3
votes
1answer
471 views

Is there an industry standard for structuring code and comments?

I've worked with a number of professional teams and it seems that class code structure ranges from highly organized to completely cluttered. I did a project with the State of California recently and ...
2
votes
6answers
755 views

Shouldn't we count characters of code and comments instead of lines of code and comments? [closed]

Counting lines of code and comments is sometimes bogus, since most of what we write may be written in one or more lines, depending column count limitations, screen size, style and so forth. Since the ...
14
votes
7answers
2k 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
4answers
1k 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 ...
75
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 ...
10
votes
7answers
902 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 ...
7
votes
1answer
13k views

What is the best way to comment a deprecated class in Java?

I would like to know the best way to add a comment to identify a deprecated class in Java. Should I remove the previous comment added to the top of the class that helps another programmer to know what ...
5
votes
15answers
1k views

What do you think of opening brace comments in source code? [closed]

I have developed a habit of writing comments in my code by putting the comments on the same line as the opening brace, after the brace. I've found that this saves vertical space. It also leaves a hint ...
13
votes
11answers
1k views

Is it efficient to attach a comment on every function? [duplicate]

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 ...
8
votes
4answers
446 views

Should the syntax for disabling code differ from that of normal comments?

For several reasons during development I sometimes comment out code. As I am chaotic and sometimes in a hurry, some of these make it to source control. I also use comments to clarify blocks of code. ...
24
votes
11answers
2k views

When do you start documenting the code? [closed]

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 ...
29
votes
17answers
3k views

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

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 ...
0
votes
6answers
728 views

What information should a good (method- / class-) comment contain? [closed]

This is something that has bothering me for a while now. I guess there are a couple of obvious important things that should go into a comment, such as: The author(s) A description of the parameters ...
3
votes
8answers
583 views

Do I Need To duplicate comments in Every File?

I have very similar code over multiple files in my project. If a client wanted some level of commented code, would I have to invest the time into duplicating the code for every file. I think it would ...
58
votes
17answers
4k 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 ...
1
vote
1answer
713 views

Metrics: Comments vs Documented API

I've been asked to run some code metrics in order to assess the quality of the code. One of the metrics was vaguely specified as "comments". I ran Sonar on my code, and while I got 10% on the ...
0
votes
4answers
255 views

Deciphering foreign code [duplicate]

What is the best strategy to go about understanding some one else's code for a medium sized project, if the code is not well documented and does not adhere to many coding standards?
2
votes
5answers
389 views

Run On Sentences in Technical Writing

This is just a question to think about. When you write technical documentation and programming comments, do you ever find yourself writing run-on sentences in order to be more precise? Is packing ...
6
votes
7answers
2k views

Is it wrong not to create Javadoc for my code?

I do a lot of Java programming at my work (I'm an intern) and I was wondering if it is generally a rule to create javadoc to accompany my code. I usually document every method and class anyways, but I ...
4
votes
3answers
806 views

How should one properly comment and license a set of code files before uploading to the public? [duplicate]

I've written a decent chunk of code over the past few days and I'm ready to git init it and push it to github. But before I do so, I want to do this the "correct" way in case anyone else wants to use ...
12
votes
8answers
3k 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 ...
22
votes
9answers
10k 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? ...
2
votes
3answers
370 views

Where should I include comments in my “self-documenting code”?

I'm currently developing a web-app by myself and have made it a point to use descriptive variable and method names (sometimes at the expense of brevity) in order to minimize commenting. The plan was ...
13
votes
6answers
6k 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 ...
-1
votes
7answers
275 views

Single line comments for multiple indented lines of code [closed]

After many years of coding, trying various programming styles, weeding out unreadable or impractical stuff, I still can't figure out one thing: what is the best way to single-line-comment multiple ...
13
votes
9answers
604 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 ...
36
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 ...
1
vote
7answers
1k views

Should you use “internal abbreviations” in code comments? [closed]

Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI ...
40
votes
9answers
29k 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 ...
7
votes
1answer
9k views

Header comment format

I realize that the "header comment" format varies from programmer to programmer, but what would be an example of a "good" header comment?
-1
votes
4answers
218 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 ...
9
votes
11answers
2k views

Version control comments - past or present tense [closed]

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.
18
votes
11answers
2k views

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

I've often seen such comments be used: function foo() { ... } // foo while (...) { ... } // while if (...) { ... } // if and sometimes even as far as if (condition) { ... } // if ...
57
votes
24answers
7k 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 ...
22
votes
21answers
14k 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: ...
2
votes
3answers
351 views

How does one pluralize <see cref=“Notation”>'s?

What is the most appropriate way of writing this comment: /// <summary> /// Order - Identifies the ordinal location of this category /// relative to other listed categories. ...
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 ...
34
votes
13answers
10k 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, ...
0
votes
2answers
165 views

How to systematize tagging in code? [closed]

There are several almost standard tags used in comments: FIXME, TODO, BUGBUG. Which other tags do you use and for what? Are there any standards on using them, i.e. format (supplementing with date ...
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 ...
9
votes
7answers
664 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 ...
5
votes
4answers
386 views

Correct alignment when outcommenting code

Suppose I have some code void some_block(void) { some_statement_1(); some_statement_2(); some_statement_3(); } Now I wish to out-comment statement #2, but here I never can find a way ...
6
votes
6answers
286 views

Divisional/Sectional comments, good or bad?

I know the general trend against comments explaining how something works, and how it's a good idea to use them only to explain why you're doing what you're doing, but what about using comments as a ...
9
votes
9answers
2k views

What are your thoughts on Periods/Full Stops in code comments? [closed]

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 ...
8
votes
6answers
981 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 --> ...
6
votes
6answers
7k views

What should I include in my class documentation header

I'm looking for informative class documentation format for my Entity, Business Logic and Data Access classes. I found following two formats from here Format 1 ...
43
votes
11answers
14k views

Why are /// comment blocks important?

Someone once said we should prefix all our methods with the /// <summary> comment blocks (C#) but did not explain why. I started to use them and found they annoyed me quite a bit, so stopped ...
15
votes
5answers
287 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 ...