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.

4

I would heavily recommend not to include notes about considering design options and trying to make judgment as comments in the source code, these are never "short enough". Only the final results of that thought process, but that is quite different from what the OP was asking.

Doc Brown
– Doc Brown

2016-08-26 21:53:41 +00:00
Commented Aug 26, 2016 at 21:53
3

I often find myself in discussions along the lines of "why did we make this decision." It's incredibly helpful to go back to my daily project notes to provide context, including the alternatives we discussed. I think I'm in good company: according to The Everything Store Jeff Bezos does the same.

kdgregory
– kdgregory

2016-08-26 22:31:54 +00:00
Commented Aug 26, 2016 at 22:31
8

@DocBrown - sometimes it is a good idea to include reasons why you did not use other possible methods/algorithms so a future developer won't try to replace what you've done

HorusKol
– HorusKol

2016-08-26 22:56:43 +00:00
Commented Aug 26, 2016 at 22:56
1

@HorusKol: sure, in some rare cases, that is trivial common sense. But that is quite different from "documenting the decision-making process".

Doc Brown
– Doc Brown

2016-08-26 23:59:26 +00:00
Commented Aug 26, 2016 at 23:59
1

@DocBrown right, I don't think anyone wants pages of notes in their source code. :)

mcknz
– mcknz

2016-08-27 02:24:57 +00:00
Commented Aug 27, 2016 at 2:24

| 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 »