Questions tagged [comments]
Questions about writing comments in code.
202 questions
4
votes
5
answers
429
views
Why don't many languages implement an everything-before-is-a-comment symbol?
Python and PowerShell use # to denote to the parser that everything after them until the line break is a comment. They even provide block comments for multiline situations. However, there is no ...
5
votes
12
answers
5k
views
Are comments obsolete in favor of Generative AI?
With generative AI, you can just ask it to explain the code to you. In my experience, it is reliable and accurate - which cannot always be said about manual comments. I am specifically referring to ...
- 1,563
23
votes
9
answers
7k
views
Using commented dashes to divide up code chunks [closed]
I'm taking another crack at learning Java with the aim of getting a job. As I write code, I sometimes find it quite difficult to navigate my code using the formatting I often see in tutorials. ...
- 341
18
votes
6
answers
5k
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,003
4
votes
6
answers
667
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 ...
- 243
3
votes
2
answers
318
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 ...
- 213
9
votes
4
answers
667
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
301
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,844
2
votes
3
answers
2k
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
3
votes
4
answers
7k
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 ...
- 43
50
votes
6
answers
13k
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,661
2
votes
1
answer
197
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. ...
- 567
4
votes
5
answers
277
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
137
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
285
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