Questions about writing comments in code.

learn more… | top users | synonyms

0
votes
3answers
116 views

Should method comments be written as if everything will work?

If I have a method to look for a valid email address in an array, that could either: Return the email address Return false if an email wasn't found. Throw an exception if an email was found, but it ...
28
votes
4answers
3k views

How are comments usually parsed?

How are comments generally treated in programming languages and markup? I am writing a parser for some custom markup language and want to follow the principle of least surprise, so I'm trying to ...
2
votes
4answers
124 views

Should actions / methods be conjugated in comments?

For example, which of the following is correct ? // Return hello -- or -- // Returns hello function greeting() { return "Hello"; } I personally never conjugate them but I am wondering how ...
0
votes
1answer
81 views

Should I document expected call-sequences when call-order matters?

In dynamically and weakly-typed languages*, I often find myself with structures like the following pseudocode: class Stateful: # [ various datamembers / attributes / properties / fields / etc. ] ...
-2
votes
4answers
115 views

Best possible way to comment? [closed]

My question is simple, how should I comment during development so that it can be beneficial in the following cases: Understandable for my seniors while code reviewing. Should be able to search my ...
2
votes
2answers
181 views

Is there anything wrong with putting comments in an HTML closing tag?

I often write comments like this <div id="wrapper"> ... </div> <!-- id="wrapper" --> But what if I wrote them like this? <div id="wrapper"> ... </div id="wrapper"> ...
0
votes
3answers
185 views

In the spirit of consistency, is it acceptable to comment everything equally? [closed]

Consistency is something I value (at an OCD perfectionist level to be honest). I can live with not writing any comments and focus on producing good, refactored, readable code -- or, if I must comment, ...
10
votes
4answers
1k views

Why should comments / documentation of a JavaScript function include so much? [duplicate]

I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this: /** * Represents a book. * @constructor ...
16
votes
7answers
1k views

Writing comments for some small code with rather large background [duplicate]

So I had to write some code related to splitting Bezier curves into parts. I read through several references and particularly referred this rather detailed one. The final code outcome is however ...
22
votes
6answers
3k views

Explaining new or uncommon syntax in comments [duplicate]

As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats ...
68
votes
9answers
8k views

Clean Code comments vs class documentation

I'm having some discussions with my new colleagues regarding commenting. We both like Clean Code, and I'm perfectly fine with the fact that inline code comments should be avoided and that class and ...
1
vote
1answer
160 views

What is ## used for?

I have looked at other questions about this and the general consensus seems to be that ## is used for commenting out code. However, in the Interactive Editor for Python, prefixing a line with ## ...
3
votes
3answers
291 views

Should code comments explain the control flow?

Should comments explain how the application control flow works? For example, the relationships between classes, how this function is used by other functions, and what we are trying to do with these ...
70
votes
17answers
15k views

How can I ask my boss (in a polite way) to comment his code?

I am being taught by my boss (I just finished school and he wanted someone with a little programming experience, so he chose me to train me on what that company specializes in) and started working ...
8
votes
3answers
1k views

Is reading javadoc preferable to reading source code to familiarise yourself with a library?

I just came across the following in a lab manual at university: You do need to study the interfaces of the classes by generating the javadoc for them so you know what operations are provided (feel ...
0
votes
1answer
66 views

Comments for a class that isn't an entity

According to Java's commenting conventions, classes comments should describe a "thing", rather than "actions". It is easy when the class IS a thing (ex. a Clown), but what if it isn't? In this case, ...
2
votes
4answers
416 views

How does a developer code in anticipation of change? [closed]

I ask this question based on the fact that currently my environment is under constant change due to the type of work we do. We do not always work on a project bases we often have smaller changes that ...
3
votes
3answers
185 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
1answer
168 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 ...
1
vote
3answers
93 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-* ...
1
vote
3answers
200 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}. ...
4
votes
3answers
541 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() ) { ...
190
votes
16answers
33k 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
0answers
36 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
156 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
481 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 ...
2
votes
4answers
298 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 ...
5
votes
5answers
2k 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
252 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" ...
1
vote
2answers
135 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?
4
votes
2answers
2k 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 ...
1
vote
1answer
102 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 ...
2
votes
2answers
713 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 ...
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 ...
0
votes
0answers
939 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
244 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++ ...
2
votes
4answers
463 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 ...
2
votes
2answers
535 views

Documenting the effect of std::move

As my team move towards embracing the new features in C++11, I'm struggling with how to make the side-effects of std::move self-documenting in the code. The issue is that an object that has been ...
2
votes
2answers
51 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
542 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 ...
11
votes
2answers
412 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 ...
27
votes
8answers
2k 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 ...
18
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
2answers
314 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 ...
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. ...
74
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 ...
5
votes
2answers
195 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
421 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
5k 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 ...