Skip to main content
Software Engineering

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.

3
  • I'd recommend linking to public documentation for cases like this, instead. Claiming that the current implementation is using "the best" algorthm is going to bit-rot in long run when better algoritms are found so you shouldn't write such comments. It's good to add comment that some sequence of code is to avoid padding oracle attack because then future developer will know not to touch the code without understanding what is padding oracle attack or how the existing code avoids that. Document why code is needed with a comment. Commented Jan 19, 2023 at 14:45
  • If it's just "this was easiest to implement" or "this was considered the most effective algorithm while it was written", it doesn't deserve a comment in the code. All code should always belong to one of those cases. Commit message is enough for such less important details. Commented Jan 19, 2023 at 14:46
  • Legend says that there's some value adding a comment saying "Notice! This section of the code has been tried to been rewritten 13 times to improve performance. If you try and fail, increase this counter." for code that appears easy to optimize but cannot be optimized in reality. It might be good idea to have a comment along those lines to avoid wasting more future work if the context is truly hard. Commented Jan 19, 2023 at 14:49