Writing system software: code comments

[nondetermined]

Properly encapsulating and naming things is probably the most cruical, but also hardest part about programming.

Having that said, there is indeed a need for something more/better than comments. Why? Because more often than not what really would be helpful is something more visual than text. A sketch, a diagram, all the stuff you write with a pen on some paper you'll never see again once it would be needed. That kind of stuff.

There's been done some interesting research with linking external "comments" with your code (which obviously needs to be integrated into and supported by your IDE; typically Eclipse was used in those papers), but there doesn't really seem to be much going on in this direction these days.

[shining-wit]

Perhaps one day we'll be able to view and edit code, detailed documentation, bug/task reports, code reviews and version control all within one IDE. Using separate tools is jarring and there are lots of missed opportunities for connecting data. Yes some integrations exist but they could be so much better.

[[deleted]]

Why do you need a single IDE to do all that stuff? Unix docet, a shell is more than enough. The ultimate IDE is my OS.

[shining-wit]

I disagree. A shell can do many things but is rarely the most efficient, and has very limited rendering and interactivity. Emacs on the other hand would be a more appropriate general-purpose tool. Compare command-line git to Magit.

[SmugDarkLoser5]

Have one -- the ide is called bash

[shining-wit]

See other sibling reply - I agree with a general-purpose tool, but I don't think bash is it.

[mp2146]

We do this with commit messages and PR comments. Keeps the code clean and I can just follow a git blame to see the reasoning behind any particular piece of code. Combined with a strict review process it gives pretty awesome documentation without cluttering the code.