Questions about writing comments in code.

learn more… | top users | synonyms

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. ...
75
votes
13answers
4k views

What are examples of comments that tell you why instead of how or what? [closed]

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about ...
6
votes
2answers
200 views

how to pluralize 'special' terms e.g. class names

Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names. It ...
5
votes
3answers
441 views

Why do some opensouce libraries lack comments?

I don't know if this happens to most Opensource libraries, but many of I know and use (for example OpenSSL, Webkit, ...) they all lack comments, or contain very few comments. Not to mention their ...
44
votes
19answers
4k views

Forcing people to read and understand code instead of using comments, function summaries and debuggers? [duplicate]

I am a young programmer (finished computer science university but still under a year of working in the industry) and I recently got a job working on some C code for a decent size web service. Looking ...
19
votes
3answers
6k views

How to solve the problem of nested comments

It appears in not just one language that comments can't be nested. Do you have a good solution for this problem? One workaround in C/C++ and Java is to only use the single-line comment but it becomes ...
3
votes
6answers
1k 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 ...
2
votes
1answer
1k 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 ...
18
votes
4answers
4k 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> /...
67
votes
13answers
9k 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()); ...
2
votes
2answers
321 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. ...
-1
votes
1answer
341 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
143 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 ...
171
votes
23answers
16k 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 ...
9
votes
3answers
238 views

How to refer to specific areas of code in documentation?

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding ...
6
votes
7answers
562 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?
5
votes
7answers
769 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 ...
10
votes
5answers
1k 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 ...
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 ...
13
votes
2answers
2k 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 ...
22
votes
8answers
2k views

Should comments say WHY the program is doing what it is doing? (opinion on a dictum by the inventor of Forth) [duplicate]

The often provocative Chuck Moore (inventor of the Forth language) gave the following advice[1]: Use comments sparingly! (I bet that's welcome.) Remember that program you looked through - the ...
9
votes
3answers
851 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 ...
5
votes
4answers
439 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 ...
7
votes
4answers
432 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
404 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 ...
8
votes
4answers
882 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 ...
11
votes
7answers
827 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
4answers
421 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
874 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
564 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
2answers
592 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 - ...
13
votes
9answers
2k 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 ...
3
votes
2answers
274 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
722 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 ...
6
votes
2answers
305 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
453 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 ...
7
votes
6answers
603 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
165 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 ...
8
votes
2answers
977 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?
10
votes
7answers
2k 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?
16
votes
6answers
5k 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 ...
8
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?
21
votes
13answers
3k 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 ...
-1
votes
3answers
397 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 ... ... ...
68
votes
17answers
14k views

Do TODO comments make sense? [closed]

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 ...
8
votes
11answers
638 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 ...
3
votes
5answers
2k 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
155 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? [closed]

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