Much has been said about comments in programming. I feel like when I was first learning “comment everything!!” was popular advice to\u00a0newcomers which eventually shifted over to “your code\u00a0should be self-documenting!”, though I suspect the latter advice has been around for about\u00a0as long. I’ve never been a huge comment user since I wrote most of my code during short term contests, making it disposable. Mostly documenting things that might need to be adjusted later, possible problems\/deficiencies, and often using them to separate unrelated chunks of code (which is likely\u00a0a bad practice that generally indicates the code should just\u00a0be split apart). I should do a better job of documenting the API, particularly considering\u00a0how often I use dynamic languages.<\/p>\n
But after working on such a long term project\u00a0for so long, the realest purpose of comments is starting to dawn on me. Comments are band-aids for when\u00a0things aren’t ideal.\u00a0If you’ve analyzed a situation and decided to go with a compromise to get something done just\u00a0“good enough”, you can use a comment to explain the particulars of an odd line of code instead of wasting the reader’s time figuring out the chain of reasons\u00a0for\u00a0it. I’ve probably\u00a0used them for such a purpose countless times without realizing it. But there are just as many times where I’ve done something convoluted without bothering to explain it, and then had to understand it again later.\u00a0I\u00a0need to make a more proactive effort to notice these situations and then explain them for the future. It’s not as good as just having obvious behavior, but it’s better than nothing.<\/p>\n
This isn’t a mind blowing revelation so much as reminding myself by writing about it. Most people writing about “self-documenting code” will say something very similar. Though they mostly refer to it as using comments strictly for non-obvious or complicated sections of code, as opposed to just admitting it’s to alleviate\u00a0bad code. I don’t think I fully absorbed the idea when it was about “non-obvious” code. But bad code. That I understand.<\/p>\n","protected":false},"excerpt":{"rendered":"
Much has been said about comments in programming. I feel like when I was first learning “comment everything!!” was popular advice to\u00a0newcomers which eventually shifted over to “your code\u00a0should be self-documenting!”, though I suspect the latter advice has been around for about\u00a0as long. I’ve never been a huge comment user since I wrote most of… Continue reading A comment on comments<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-388","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/posts\/388","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/comments?post=388"}],"version-history":[{"count":2,"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/posts\/388\/revisions"}],"predecessor-version":[{"id":390,"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/posts\/388\/revisions\/390"}],"wp:attachment":[{"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/media?parent=388"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/categories?post=388"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.crabattack.org\/blog\/hawk\/wp-json\/wp\/v2\/tags?post=388"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}