Edit - Software Engineering Stack Exchange

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Rev

18

Self documenting code is a lie.
– yannis
Commented May 14, 2012 at 4:25
1

@YannisRizos More like an unattainable goal than an outright lie.
– Ptharien's Flame
Commented May 14, 2012 at 4:47
3

@YannisRizos: you may be right, but code which needs lots of comments is almost ever very bad code and could be almost ever written in a manner that it needs less comments.
– Doc Brown
Commented May 14, 2012 at 6:32
9

@DocBrown Depends. I've seen people documenting for loops and I've seen people claiming that a 100 loc of business logic was self documenting. Fact is that excessive comments can't hurt (except if obsolete/incorrect), and if I have to choose between excessive commenting and self documenting code, I'll always choose the first. Of course, I'd pretty much prefer balanced and to the point comments, like Oleksi describes.
– yannis
Commented May 14, 2012 at 7:09
1

@MathAttack Most decent IDEs can hide / fold comments. But yes, sometimes they just get in the way.
– yannis
Commented May 14, 2012 at 10:43

| Show 2 more comments

Correct minor typos or mistakes
Clarify meaning without changing it
Add related resources or links
Always respect the author’s intent
Don’t use edits to reply to the author

create code fences with backticks ` or tildes ~
```
like so
```
add language identifier to highlight code
```python
def function(foo):
print(foo)
```
put returns between paragraphs
for linebreak add 2 spaces at end
_italic_ or **bold**
indent code by 4 spaces
backtick escapes `like _so_`
quote by placing > at start of line
to make links (use https whenever possible)
<https://example.com>
[example](https://example.com)
<a href="https://example.com">example</a>

formatting help »
answering help »