Questions about writing comments in code.
1
vote
6answers
437 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 ...
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?
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 ...
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());
...
0
votes
1answer
97 views
Possible to Comment on a storyboard?
I recently started working for a company that has me making mockups for an app they'd like to see converted to an iPhone app. I have not been informed as to how all the boards fit together, but I do ...
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 ...
14
votes
4answers
530 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>
...
2
votes
2answers
310 views
Leaving “Else” comments
Let's say I have a not-so-intuitive if statement in my code, but only if you're new to the codebase:
def set_markets(markets=None):
"""
Will accept 'all' as markets to set all markets on.
...
-2
votes
1answer
230 views
Is there a code tag to indicate “need improvement” on code comments? [closed]
TODO indicates "task to be completed", FIXME to be fixed etc. Is there a code tag to indicate "need improvement" on code comments?
1
vote
2answers
93 views
@Deprecated as of version x.y in JavaDoc
This question & its answers are useful but not sufficient for my problem.
My Question is if I want to add a javadoc as @Deprecated As of version x.y, replaced by {@link SomeClass} in my current ...
5
votes
3answers
194 views
Commenting regular expressions
Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
6
votes
7answers
707 views
In what stage of development should comments be written?
I'm a student working an internship at a larger company, writing small business apps in C#. I've noticed that I don't comment my code as I write it. Rather, I comment my code when I'm in the ...
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 ...
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 ...
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 ...
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 ...
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 ...
6
votes
3answers
396 views
Are XML Comments Necessary Documentation?
I used to be a fan of requiring XML comments for documentation. I've since changed my mind for two main reasons:
Like good code, methods should be self-explanatory.
In practice, most XML ...
7
votes
6answers
278 views
Teaching: How can you motivate students to comment? [closed]
I remember when I was taught, "comments are the most important part of code." Or rather, when I was told that comments are the most important part of the code. I don't think I was convinced, and I ...
5
votes
4answers
169 views
Should I comment Tables or Columns in my database?
I like to comment my code with various information, and I think most people nowadays do so while writing some code.
But when it comes to database tables or columns, I have never seen anyone setting ...
-1
votes
3answers
292 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 ... ... ...
7
votes
4answers
367 views
What would be a good way to request comments?
In the project/team I'm working the frequency of comments is a little low.
One reason might be that it is not clear to the long-time devs what lines in the code really needs a comment (each part of ...
3
votes
4answers
307 views
How to discriminate commented code and documentation comments
After using version control tools, it is no longer necessary to comment out old code.
However, some team members still comment out old code. Therefore, I want to clean them up.
I want to mark ...
4
votes
1answer
170 views
Looking for VS2010 comments extension/addon
I am trying to track down a VS2010 extension that has the following features ...
Ability to display a list of types/members etc that don't have either inline code comments or documentation comments ...
1
vote
3answers
218 views
How to use correctly the comments in C/++ [duplicate]
Possible Duplicate:
Style and recommendations of commenting code
I'm learning to program in C and in my stage, the best form to use correctly the comments is writing good comments from the ...
5
votes
4answers
288 views
How are comments expressed in programming language grammars?
I'm learning how to build parsers using grammars, but I got stuck trying to express comments, because they can appear almost anywhere.
This indicates that comments can be stripped from the token ...
7
votes
8answers
984 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?
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 ...
2
votes
2answers
240 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 ...
9
votes
6answers
692 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 ...
2
votes
4answers
241 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
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.
...
0
votes
1answer
160 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 - ...
10
votes
9answers
912 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 ...
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 ...
3
votes
6answers
462 views
Should you use “internal abbreviations” in code comments?
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 ...
3
votes
9answers
308 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 ...
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 ...
0
votes
2answers
228 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 ...
0
votes
6answers
383 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 ...
6
votes
2answers
179 views
Has there been any research on 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
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 ...
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 ...
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 ...
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 ...
1
vote
7answers
442 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 ...
4
votes
4answers
161 views
proper comments for source control log [duplicate]
Possible Duplicate:
What is your typical source control commit comment?
What are suitable comments to put in the source control log?
To me this seems a similar problem (but possibly more ...
5
votes
6answers
561 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 ...
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 ...
3
votes
3answers
127 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 ...
