Sometimes comments like that are good- I totally support adding comments in code ex. to document what algorithm you are using.

Also, (quote not from public channels, but idc)
commandblockguy wrote:
The "no comments except API" rule absolutely does not apply to assembly


Assembly code, when heavily optimized, is virtually unreadable to mortals.

Since the "no comments except api docs" rule works because your code should be clean and readable even without comments, when your code is optimized to the point of obfuscation you should comment your code (as the rule no longer holds).
Honestly assembly is not that hard to read if you don't have comments. Add an API to what certain calls do, and it's perfectly understandable. Adding more comments is just confusing.
The more complex your program, and the more components it contains, the less likely it is that you will be able to remember how it works. Add good comments (without simply explaining lines, see existing tips), but also keep whatever external documentation, text, and diagrams is necessary to explain your code.

This goes 10x-100x if there's anyone other than you who will or might work on the project in the future. My viewpoint has gotten a little skewed now that I work on enterprise-scale code with many simultaneous authors most of the time, but it's still good to get into this practice with smaller-scale codebases. And if you can, get into the habit of using version control properly, including good-sized commits, feature branches, tagged releases, and PRs.
  
Register to Join the Conversation
Have your own thoughts to add to this or any other topic? Want to ask a question, offer a suggestion, share your own programs and projects, upload a file to the file archives, get help with calculator and computer programming, or simply chat with like-minded coders and tech and calculator enthusiasts via the site-wide AJAX SAX widget? Registration for a free Cemetech account only takes a minute.

» Go to Registration page
Page 2 of 2
» All times are UTC - 5 Hours
 
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum

 

Advertisement