Questions tagged [comments]
Questions about writing comments in code.
199
questions
18
votes
6
answers
4k
views
Is setRGBColor(32,128,192) a valid use of magic number?
According to When is a number a magic number?, I know magic number should not exists, so I know the following code about creating a Label from some UI framework and set the color RGB needs to be ...
3
votes
6
answers
442
views
Waiting until end of project to remove commented out code, remove unused code, and resolve compiler warnings
A co-worker of mine is working on project solo but would still like to have other team members review their code upon reaching certain milestones. Unfortunately, they also want to wait until the end ...
- 233
2
votes
2
answers
253
views
What's a good workflow for including mechanical sketches in code comments?
My team writes a lot of Python code in PyCharm to do quick simulations and calculations for our mechanical engineering work. Often, we'd like to include a little image (a hand drawn sketch, CAD ...
- 193
9
votes
4
answers
563
views
How to document alternative code I considered but didn't go with due to performance?
I write code in R, and often find myself attempting to optimize the code for better performance. In a given script that tackles a specific problem, I test different code alternatives and compare them ...
- 209
1
vote
5
answers
190
views
How to refer to an e-mail in source code comment
Sometimes there are elaborate discussions about a subject, and while finally developing the program, you want to refer to a mail ... but then people still continue mailing about the subject, so the ...
- 1,707
2
votes
3
answers
1k
views
Versioning a function/method
While this might seem more like a piece of an easy task to others, it's honestly not easy for me. At this stage, I find myself wandering how best to version my functions/methods.
What does this mean?
...
- 141
2
votes
4
answers
3k
views
Is it good practice to put comment headers into each file?
I have an Unity project with countless of C# script files and I'm working on it solely.
Although nobody else is working on it, I'm aware that some form of code documentation is crucial for my future ...
- 33
49
votes
6
answers
12k
views
Is a comment aligned with the element being commented a good practice?
I am a home, amateur developer for 25 years and I just had a bright idea regarding comments. Like all such novel bright ideas, someone has probably already done it and there is probably a consensus on ...
- 1,551
2
votes
1
answer
161
views
Are there established approaches to providing informal proofs of properties a function or system has?
I have asked about the more nebulous 'system' and functions in general, but to explain my question let me just consider a pure function.
I think of pure functions as lemma/theorems/what have you. ...
- 181
4
votes
5
answers
225
views
Approaches for comment duplication
For code, we know approaches like DRY and we tend to extract common functionality. What approaches are recommended for comments? Perhaps it's a really open question, so I'm going to go with my ...
- 161
0
votes
2
answers
125
views
Should I declare motivation when commenting? [duplicate]
When commenting code, which of the two approaches considered good practice?
Explain the content of the code, "translate" it to human - readable language, but not provide any explanation ...
- 117
4
votes
5
answers
253
views
Dealing with unwanted usages of a function
I am writing a function that I would not like to get called given a certain context and am wondering how best to convey that to possible users of the function. Assume, for exemplification, I am ...
- 150
1
vote
0
answers
51
views
What to put in which kind of comment in ClearCase?
I'm used to comments in Git and Mercurial repositories:
Commit comments, which may involve multiple files over the whole repository - has a comment. Commits without comments are possible, but rare (...
- 2,488
67
votes
13
answers
17k
views
How to avoid comments about one line of code for cleanliness
I'm trying to clean up some of my code using some best practices, and read that comments are almost always a bad idea for future maintainability. I've managed to get rid of most of them by refactoring ...
- 1,565
40
votes
9
answers
9k
views
Is there a method for differentiating informative comments from commented out code?
Throughout the course of programming, you will end up with some comments that explain code and some comments that are removing code:
// A concise description
const a = Boolean(obj);
//b = false;
Is ...
- 597
6
votes
3
answers
3k
views
How to deal with long URLs in comments that exceed the 80 characters limit?
I generally try to adhere to the 80 character limit for each line of code to satisfy my colleagues, to satisfy the linting tools, and to maintain an image of professionalism when random people look at ...
- 171
1
vote
2
answers
1k
views
Python method docstring: to use or not to use Args: Returns:
Default docstring from PyCharm automatically creates template with Args: and Returns: sections. However I have observed that this prompts people to say obvious things, frequently just stating the ...
- 149
4
votes
1
answer
260
views
How should I document a method's computational complexity in the code?
I am currently working on a project that has very little documentation overall. The team is working to change that. I am doing my part, by adding xml comments to the methods I make and the ones I edit,...
- 151
9
votes
1
answer
1k
views
What does "TILT" mean in a comment?
I'm reading Clean Code by Robert C. Martin, and the phrase TILT inexplicably appears in some code samples. Example (it's in Java, by the way):
...
public String errorMessage() {
switch (...
- 201
2
votes
1
answer
178
views
Are file summary comments a good way of knowing what each file does?
I want to know if including a file summary comment at the beginning of each file is a good way of knowing what each file does or is there a better way.
user157989
3
votes
1
answer
539
views
Alternative for commented out code that will be used later
I had to implement a module that after completed, the client suddenly asked that for a while it would not need to be displayed, so I was told to comment it out (since we probably will use it later) ...
- 139
34
votes
6
answers
19k
views
Why is it wrong to comment out code and then gradually remove it to keep track of what I've already done and what remains to be done?
Whenever I find out that a large portion of my code needs to be changed, either because it is incorrect or because it needs to be adapted to major architectural changes necessited by other reasons, ...
- 3,527
-1
votes
2
answers
873
views
Is it good practice to add comments above generated fields?
Every time I let Eclipse generate a field (most often a serial version UID), it adds a comment above it. Example:
/**
*
*/
private static final long serialVersionUID = 6347144762354188381L;
This ...
- 300
0
votes
1
answer
1k
views
Should I add XML comments in DTO models or entity models
I have 2 models, DTOs and database models (entities) that map to the database.
I usually put XML comments above the properties to describe what are they for.
class MyEntity
{
/// <summary>
...
- 1,529
1
vote
2
answers
130
views
Links to documentation in comments? [duplicate]
I sometimes put a link to the site where I copied a chunk of code from in case I forget what it does. Is this a bad practice? Should I copy the explanation from the site instead of linking to it?
5
votes
3
answers
5k
views
How do you denote a variable in a comment?
Let's say I have the following function in Python:
def foo(one, two):
return one + two
And I want to document it with "adds one to two".
However, this is confusing, because I could just mean ...
- 667
6
votes
5
answers
2k
views
Documenting design decisions in code comments?
How can I best document a code design decision in my source code? Should I just add a massive comment at a point I feel is right?
Or should I just create a separate file?
This issue is important for ...
- 569
7
votes
6
answers
5k
views
Should //given //when and //then comments be included in unit tests?
I've joined a new team of great colleagues and a difference of opinion has come up concerning including //given //when and //then comment blocks in unit tests.
For example
public void ...
- 305
98
votes
12
answers
16k
views
My client wants 25% of comments in my current project, how to react? [closed]
junior developer here.
I am currently working alone on a web application for a big client of my company. I started last month.
The client wants at least 25% of comments in each of its software ...
- 553
9
votes
6
answers
2k
views
Is it generally helpful to include JIRA issues in code comments?
Once in a while, I leave comments like
# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.
or
# We only need to use the following for V4 of the computation....
- 327
13
votes
3
answers
2k
views
Are docblock typehints redundant when using strict typing
I have a quite large private codebase which has evolved for about ten years now. I'm not using phpDocumentor but since using docblock sections has become quite the standard in open source projects I ...
- 241
4
votes
4
answers
466
views
Which is better, one central detailed comment, or several smaller ones?
To restate the question: Which is better, one central detailed comment, or several smaller "sprinkles"?
Bear with me while I set up the scene:
I've got this function for popping a value from a queue ...
3
votes
2
answers
2k
views
Additional spacing before an inline comment [closed]
Early on in my career I was advised to add additional spacing between source code and an inline comment, like so:
de_cologne = (i == 4711 # 1
and j == 1799) # 2
Note the two spaces.
...
- 174
1
vote
1
answer
187
views
Are comments at the top of a source file a bad idea? [duplicate]
I use Xcode to edit my source files, and typically a file will look like this
//
// Queue.swift
// SomeCompany
//
// Created by Someone (Job Title) on 26/06/2017.
// Copyright © 2017 SomeCompany. ...
- 119
1
vote
1
answer
97
views
Making control flow explicit through printing instead of using comments?
I would have the opinion and good practices in script programming about using print statements to materialize the control flow (I usually use an anchor mark, then the name of the function just entered,...
- 111
-2
votes
2
answers
304
views
Is it ideal to put code comments in an official release?
I will release a program (not Alpha/Beta/Testing versions). Should I remove the comments in the code?
I have some comments that I added to make the code less confusing to me, but since the program ...
- 115
2
votes
1
answer
2k
views
Describing JS program flow in @fileoverview
I have to edit other people's JavaScript code. The code usually loads some data from a Web API, generates a table, places it into the HTML page, and attaches some event handlers.
Due to the async ...
user238671
0
votes
1
answer
93
views
Should requirement/issue number/code be included in the comments of the source code? [duplicate]
I am working on a number of maintenance projects and I always include requirement/issue number/code in the the comments whenever I am adding or changing code. In such way I provide traceability from ...
- 1,003
6
votes
1
answer
2k
views
Style: line length and wrapping of comments in JavaScript [closed]
I'm fine with staying under 80 characters per line for code (even if some consider that limit outdated), but I'm split (no pun intended) when it comes to splitting comments over multiple lines, versus ...
- 896
5
votes
3
answers
451
views
How to avoid falling into the trap of not commenting code? [duplicate]
I've been working on a project for about a month now. I am extremely familiar with the code and understand it to the extent where I feel that it is so easy to understand, that most methods don't need ...
- 169
52
votes
7
answers
9k
views
TODO comments with deadlines?
Background
I'm working in a team that's looking to implement zero-downtime deployments. We're planning on using a blue/green deployment strategy in order to achieve this. One of the things I'm ...
- 575
1
vote
1
answer
101
views
Should I doxygenate implementation files in a library of mine, in addition to the headers?
I'm in the process of writing Doxygen comments for this library of mine; it's a header-mostly C++ library, but it does have some code which gets linked rather than included.
For that code, which has ....
- 2,488
6
votes
1
answer
1k
views
Abuse of XML comments to keep comments up-to-date (in C#)
Problem:
Comments deteriorate when renaming a variable/class/method/etc in Visual Studio. Occurrences of said symbol in comments do not get updated by refactoring (no surprise, how could VS know).
...
- 169
4
votes
3
answers
162
views
Is the following comment clear: "Until contested" [closed]
Suppose that you see the following pattern in code:
function foo() {
...
var someFlag = false; // Until contested
for/while/if () {
...
// Possibly deeply nested in some ...
- 51
6
votes
2
answers
7k
views
What is the difference (if any) between REM statements and comments?
I have recently come across the term REM statement and wondered, is it synonymous with comment?
- 309
-4
votes
2
answers
799
views
What to do with old code? [duplicate]
Often I change code but I don't know if I might need the old one, I can leave it under comment but then I find myself with lots of green lines while I hardly can read the real code.
Thanks.
0
votes
6
answers
284
views
Using HTML id or class instead of comments
I have two elements inside a container. I don't need to give the two inner elements any id or class since they require no CSS or JS references.
Is giving them an id just for the purposes of ...
- 201
150
votes
17
answers
44k
views
Coding standard for clarity: comment every line of code?
I've worked in shops that produce life critical software and I've dealt with commenting rules that were meant to keep the code readable and potentially save lives. In my experience though the ...
- 103k
13
votes
1
answer
370
views
Introducing additional local variables as comment replacement
Is it good style to use additional, technically superfluous, local variables to describe what's happening?
For example:
bool easyUnderstandableIsTrue = (/* rather cryptic boolean expessions */);
if(...
- 197
8
votes
3
answers
2k
views
"Comment everything the right way" and "Instead of writing comments, write more readable code." - Both valid strategies?
When trying to learn about proper comment practices, I found a lot of conflicting opinions, and it's obviously a very subjective topic. So I'm not going to ask "Should I comment, or should I not?"
...
- 151