Questions about writing comments in code.
22
votes
4answers
2k 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
119 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
74 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
111 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
156 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
172 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, ...
9
votes
4answers
880 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
2k 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 ...
65
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
158 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 ## ...
1
vote
3answers
270 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 ...
69
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
64 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
338 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
181 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
160 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
192 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
534 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() )
{
...
188
votes
16answers
32k 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
151 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
412 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
291 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
251 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
132 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
101 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
649 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 ...
36
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
881 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
235 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
459 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
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
480 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 ...
10
votes
2answers
402 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
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 ...
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
306 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
189 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
417 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
4k 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 ...
2
votes
2answers
339 views
Is it bad to use giant label comments to mark off sections of code? [duplicate]
So I have a fairly big class (nearly 200 lines, so not gigantic). It started to be hard to find parts of the code, so I started making giant comments like the following:
...
2
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 ...
