Questions about writing comments in code.

learn more… | top users | synonyms

2
votes
4answers
291 views

Linking in code comments (to other unique anchors/comments)

How would you recommend creating "anchors" in code comments, so that during maintenance, developers can easily cross-reference other code comments. I realise that software should be intelligently ...
10
votes
6answers
759 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 ...
12
votes
6answers
472 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. ...
0
votes
1answer
323 views

Commenting Code AS3 - Not being an API

How should I comment a method? What are the best practices on commenting code? Example: /* Checks if a color is allowed in a given point * of the bitmapdata of the current floor * @param value - ...
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 ...
2
votes
2answers
259 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 ...
3
votes
9answers
394 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 ...
0
votes
2answers
395 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 ...
6
votes
2answers
258 views

What has research shown about the effectiveness of comments?

I have been arguing with a friend about the necessity of comments, and the efficiency of different comment styles. The argument ended quite fast, as we could not find any research - or essay - that ...
8
votes
8answers
408 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 ...
5
votes
6answers
575 views

Should I add MSDN notes or Stack Overflow links to source code? [duplicate]

Possible Duplicate: Is it OK to put a link to Q&A sites in a program's comments? I'm creating a powershell / C# host and want to add the following comment // This method cannot be ...
4
votes
3answers
135 views

Is there a difference between the quotes in `help',``help“, 'help' and ”help"?

Sometimes I find in the source code files comments have quotation marks like these ,notice the ` : `help' ``help" For example, these are comments from GNU cat source code file, cat.c: /* Plain ...
7
votes
2answers
473 views

DRY way to write Javadoc on overload methods

I want to write Javadoc in DRY way. But the oracle document about Javadoc says write same thing again in overload method comment. Can't I avoid repetition?
8
votes
7answers
1k 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?
15
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 ...
7
votes
8answers
1k views

Why does everybody write to-do comments in capital letters? [closed]

I'm doing the same. When there is something "to-do" in my code, I write //TODO .... But I'm curious to know when this started and if there is a reason for writing "to-dos" in all capital letters?
18
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 ...
18
votes
10answers
2k 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 ...
-1
votes
3answers
325 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 ... ... ...
59
votes
16answers
5k 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 ...
9
votes
11answers
584 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 ...
2
votes
5answers
843 views

Why should you document code? [duplicate]

Possible Duplicate: “Comments are a code smell” I am a graduate software developer for an insurance company that uses an old COBOL-like language/flat-file record storage system. ...
5
votes
1answer
147 views

Should code comments have scope?

I am asking this because I have seen places where, whoever coded initially had provided proper comments, but later on modifications were made to the code but the comments were left untouched. I ...
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 ...
8
votes
5answers
292 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 ...
1
vote
1answer
413 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
275 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
623 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 ...
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
4answers
644 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 ...
3
votes
8answers
7k views

Is there a symbol or shorthand for “and is increasing/decreasing”?

This usually happens when I'm writing to developers or other IT professionals. The context would be something along the lines of ". . . measured at 100 MB/s (and is increasing)." On paper or a ...
73
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
613 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 ...
3
votes
1answer
7k 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 ...
14
votes
11answers
797 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 ...
8
votes
4answers
419 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. ...
23
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 ...
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 ...
1
vote
6answers
517 views

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

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
563 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 ...
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 ...
3
votes
4answers
350 views

Does a prose to code compiler exist?

I have seen some horrible code in my time including people virtually duplicating the code in comments // add 4 to x x+=4; // for each i in 0 to 9 for (int i = 0; i < 10; i++) { // multiply x ...
1
vote
1answer
329 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
169 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
331 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 ...
4
votes
5answers
370 views

What is the right level of granularity for code commenting?

Commenting in code I believe is very important but recently I've been reviewing code that has left me wondering particular this one. //due to lack of confidence with web programming leaving this ...
5
votes
7answers
870 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
496 views

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

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 ...