Questions about writing comments in code.

learn more… | top users | synonyms

3
votes
3answers
162 views

Is it misleading to label code as a particular design pattern if it only loosely fits the definition?

Background: I have a rough, but working understanding of ~15 design patterns. It's been my experience using design patterns in my own projects that the resulting implementations usually end up as some ...
1
vote
0answers
33 views

First programming job with few resources to learn from [duplicate]

I recently started my first programming job after working for a couple of years developing websites. This new company focuses on PHP and has had only one developer responsible for the code since the ...
17
votes
3answers
3k 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 ...
-1
votes
7answers
264 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 ...
1
vote
1answer
474 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 ...
0
votes
1answer
121 views

Is there a particular coding standard with comments between function name and body?

I'm integrating with a shipping API built in php. They have a strange coding standard where the comments are between the function name and the first curly bracket.. which - subjectively - makes the ...
0
votes
3answers
116 views

Add or leave comment for simple race condition logic? [duplicate]

I'm a huge proponent of removing comments for stuff that should be really clear anyway. Stuff like // remove object from list. A pattern you come across now and than is the preventing of race ...
1
vote
3answers
82 views

Should I mark what blocks mean in data-* attributes?

I was writing a webpage today with a comment after the start of every major section. Instead of using a comment, which comes with the bulgy <!-- --> syntax, could I instead put this in a data-* ...
0
votes
2answers
122 views

Referencing StackOverflow questions in comments [duplicate]

Often when coding I'll get stuck on a particularly tricky problem and will go about searching for a solution. More often than not this leads me to a StackOverflow question that provides a full or ...
1
vote
3answers
168 views

Is there a need to comment obvious parameters? [duplicate]

Most of the time, when I comment a method, I'll follow this structure. /** * Short description of what the method does * * @param {Type} name. Description of the variable. * * @return {Type}. ...
1
vote
4answers
408 views

Would comments increase the chance of being fired? [closed]

I have had this burning question for a while. If I have a job and I comment my code well, to the point that anybody can now understand my hard work, would it make me less indispensable to the company? ...
4
votes
3answers
481 views

Intentionally incorrect use of language features, specifically “ref” in C#, as a hint to colleagues

I recently came across a piece of code something like this (roughly C#): public bool ValidateStuff(ref ArrayList listOfErrors, Stuff thingsToValidate) { if (!thingsToValidate.isValid() ) { ...
160
votes
15answers
26k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
0
votes
1answer
128 views

if else brackets on same line, best comment style? [closed]

I used to do this: // If the cat is black if ( $catColor == 'black' ) { ... } // Otherwise eat a taco else { ... } But I've more recently started to move toward this style of conditional ...
17
votes
12answers
2k views

Correct comment to put for boolean function arguments that are “false”?

From some open source projects, I gathered the following coding style void someFunction(bool forget); void ourFunction() { someFunction(false /* forget */); } I always have doubt about what ...
1
vote
4answers
479 views

Does a prose to code compiler exist? [closed]

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

Changelog in Comments Versus Source Control Log [duplicate]

Until recently, I have worked on a code base which kept change logs both as a table in the header section of each file and as comments in source control. In practice, only the header comments were ...
0
votes
2answers
154 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 ...
6
votes
7answers
527 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?
4
votes
6answers
2k 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 ...
1
vote
3answers
193 views

Commenting strategies in C# & asp.net web api

I've been working on a ASP.NET Web Api 2 project as a learning exercise, and I was wondering what the norm regarding commenting is. I use the Repository / Service Pattern, and everything is very much ...
12
votes
8answers
2k 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 ...
2
votes
4answers
252 views

Is it normal needing time to understand code I wrote recently [closed]

By recently I mean some weeks ago. I am trying to continue a project I left 2 weeks ago and I need time to understand some functions I wrote (not copied from somewhere) and it takes me time. Normally ...
6
votes
2answers
267 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 ...
3
votes
5answers
844 views

How should I handle exception that *should* never be thrown? [duplicate]

What is the best way to handle errors that shouldn't ever happen? My current way to do this is to throw an exception if the 'thing that shouldn't happen' does happen, like so: /* * Restoring from a ...
2
votes
2answers
236 views

Are multi-line comments a critical facility in a modern language?

I'm trying to convince the designers of a language that multi-line comments with an arbitrary start and end are important, and should be included. Currently there is only a "comment-to-end-of-line" ...
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 ...
60
votes
13answers
8k 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
2answers
115 views

Is it a bad practice to cite URLs as references in comments? [closed]

Sometimes I think it's useful to cite a webpage (e.g. Stack Overflow questions) to justify and explain a piece of code. Is this considered bad practice?
3
votes
2answers
536 views

Asterisks in Multi-line comments

Using Visual Studio 2012 with C#, when I write multi-line comments, VS automatically begins each line with an asterisk, like this: /* * * */ I was just curious if this was the case in ...
37
votes
16answers
6k views

Good idea to put bug numbers in a comment in the beginning of the source file? [closed]

Is it a good practice to put bug numbers in the file itself inside a header comment? The comments would look something like this: MODIFIED (MM/DD/YY) abc 01/21/14 - Bug 17452317 - npe in drill ...
1
vote
1answer
91 views

Are there any standards for separating different kinds of comments (explanatory, debug, to-do, etc.)?

For a while now I've been in the habit of differentiating different kinds of comments in my code. //this is an explanatory comment //!this line was commented out for debug purposes, DO NOT SHIP WITH ...
22
votes
21answers
8k 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: ...
0
votes
2answers
337 views

Where to put comments, class declaration or constructor?

For a given class, where should the comments about the purpose of the class go? /// <summary> /// <----------------- describe the class here (1)? /// </summary> public class ...
45
votes
19answers
3k 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 ...
0
votes
0answers
480 views

Commenting MVC applications [duplicate]

I've recently realised that my workplace doesn't comment their ASP.NET MVC applications. By 'doesn't document', I mean there is probably 1 line of comment per model/view/controller. No file purpose, ...
-1
votes
1answer
206 views

Is using non-standard single-line comments fine in C? [closed]

I noticed Visual C++ 2010 (my current environment) and XCode both allow non-standard single-line comments in my C programs. Since these are both my target platforms, I assume it's fine to use it? VC++ ...
0
votes
3answers
444 views

Why are there so few comments in C/C++ code? [closed]

I'm a web developer primarily, and I've been learning C/C++ and trying to get involved in some open source projects. Something I find very unusual is the lack of comments in C/C++ source code (I've ...
-2
votes
1answer
95 views

What effect does the utilization of pseudocode and comments have when a software engineer designs software? [closed]

I am a programmer by trade so in my English Class ENC 1102, when we were asked to come up with a discourse community in which we could relate the use of writing skills I thought about pseudocode and ...
2
votes
4answers
423 views

Private comments in git

I need to add a feature to some code in a big project and due to the complexity I find it very helpful to add detailed comments to many lines to keep track of what's happening. This is only for my own ...
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 ...
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 ...
2
votes
2answers
50 views

Infrastructure-related additions in commit comments

For the sake of this question, let's agree on this definition of "good commit message" from here: Your comment should be brief and to the point, describing what was changed and possibly why. and ...
1
vote
1answer
262 views

Best practice for comments above methods in a grails application?

I'm writing a grails application and am not sure what the best practice is with regard to comments outside of method blocks. I've done a bit of research and there seems to be conflicting views on how ...
61
votes
16answers
6k 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 ...
2
votes
6answers
647 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 ...
10
votes
2answers
370 views

Is spreading code with refactoring comments a good idea?

I am working on a "spaghetti-code" project, and while I am fixing bugs and implementing new features, I also do some refactoring in order to make the code unit-testable. The code is often so tightly ...
0
votes
2answers
276 views

How to write comments to explain the “why” behind the callback function when the function and parameter names are insufficient for that?

How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on. I ...
8
votes
4answers
421 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. ...
27
votes
8answers
1k views

good replacement for commenting out code? [duplicate]

It bothers me to see commented out code and it seems often-times a symptom of developers not being proficient in advanced source control features, but on the other hand source control does not really ...