{"id":394,"date":"2017-09-06T07:09:23","date_gmt":"2017-09-06T14:09:23","guid":{"rendered":"http:\/\/blog.submain.com\/?p=394"},"modified":"2017-09-06T07:09:23","modified_gmt":"2017-09-06T14:09:23","slug":"code-comments-avoid","status":"publish","type":"post","link":"https:\/\/blog.submain.com\/code-comments-avoid\/","title":{"rendered":"Not All Code Comments Help: What Should You Avoid?"},"content":{"rendered":"

The debate over whether or not to comment your code<\/a> rages on, showing no signs of stopping. ?Catalogers of anti-patterns include code comments as a code smell<\/a>?because they explain problems in your code instead of fixing them. ?Not so, counter people on the other side of the aisle, sometimes angrily<\/a>. ?No doubt the conversation becomes only more civil and even-keeled from there.<\/p>\n

So-called religious wars like this emerge for a variety of reasons. ?Human nature causes us to get attached to our own decisions<\/a>?and to assume people making different choices than us do so as a result of personality defects<\/a>. ?But in the case of code comments, even more complicating factors exist. ?One person, when speaking about code comments, may mean inline explanatory comments. Another may mean?documentation for the sake of IntelliSense<\/a>. ?People will argue angrily before realizing they’re not even talking about the same thing. ?Then folks come along and try to find a diplomatic, consensus-building middle ground<\/a>.<\/p>\n

Today, I’m going to do none of those things. ?I’m going to utterly punt on words of wisdom about how, when, and why you should comment. ?Instead, I’ll have a bit of fun by walking through something a lot of us can probably agree on. ?I’m going to talk about the sorts of comments that nobody should write, whatever your stance on the broader issue of commenting.<\/p>\n

If you’re a general comment-hater, then of course you’ll agree that people shouldn’t write these comments because they shouldn’t write any. ?But even if you’re a comment enthusiast, you’ll concede that not everything that people ever put after two slashes (or a pound or whatever) deserves to be immortalized in your codebase.<\/p>\n

Here are categories of comments that should not be.<\/p>\n

<\/p>\n

Thanks, Captain Obvious!<\/h3>\n

Let’s start off with a simple example. ?I’ve never, in my life, seen anyone defend this. ?And yet, I’ve seen people do it plenty of times. ?I’m talking about the mind-numbingly obvious comment.<\/p>\n

public void SendMailer(Customer customer)\n{\n    foreach (var address in customer.Addresses) \/\/Cycle through all of the customer's addresses\n        _mailService.SendGreting(address); \/\/Call the mail service to send a greeting mailer to the address\n}<\/pre>\n
This sort of thing usually comes from a good place. ?People internalize the wisdom to consider those coming after them and to err on the side of too much, rather than too little, information. ?But at some point, it just becomes pointless noise.<\/p>\n
Maintenance programmers need context — not programming lessons. ?They know what foreach() does, and they understand the basics of calling a method. ?So save yourself some effort and the codebase some noise, and don’t bother explaining language basics with your comments.<\/p>\n
End of Scope Comments<\/h3>\n
Have you ever seen people do this<\/a> in code? ?At the end of a control flow block in code, they place a comment. ?For instance, let’s amend our previous example a bit:<\/p>\n
public void SendMailer(Customer customer)\n{\n    foreach (var address in customer.Addresses)\n    {\n        _mailService.SendGreting(address);\n    } \/\/end foreach\n}<\/pre>\n
“What’s wrong with that?!” ?I can feel some of your outrage radiating through the internet ether. ?”That can really help you understand where a gigantic loop ends!”<\/p>\n
I’ll concede the point that such a comment can indeed help when you have gigantic loops with many levels of nested scope. ?In this case, the problem isn’t the comment, per se, but rather the maintenance nightmare that you’re using it on.<\/p>\n
So forget these comments. ?They normalize this problematic coding style and make your team numb to it. ?Instead of commenting on end of scope, extract methods until you no longer have scope blocks so large that you can’t see where they started.<\/p>\n
Source Control via Code Comments<\/h3>\n
Early in my career, I remember seeing (and, if I’m honest, writing) things like this:<\/p>\n
\/********************************************\n* Author:      Erik Dietrich\n* Method:      SendMailer\n* Arguments:   Customer: the customer for whom to send the mailer\n* Returns:     void\n* Modifications\n* 12\/22\/2016   Created\n* 1\/14\/2017    Removed the mailer template parameter\n* 1\/17\/2017    Refactored to use the mailer service\n* 2\/22\/2017    Removed one line foreach brackets to conform with coding standard\n* 4\/4\/2017     Adding code coverage\n* *******************************************\/\npublic void SendMailer(Customer customer)\n{\n    foreach (var address in customer.Addresses)\n        _mailService.SendGreting(address);\n}<\/pre>\n
Now, in my defense, Visual SourceSafe dominated the landscape early in my career. ?So source control wasn’t exactly a sophisticated and slick piece of tooling. ?But nevertheless, it existed.<\/p>\n
Why am I talking about source control? ?Well, because tracking the history of a method in code comments needlessly recreates source control, and poorly at that. ?If people want to get context and understand a method’s history, your source control offers a much better and less error-prone way. ?Don’t use (abuse) comments this way.<\/p>\n
The Dog Ate My Homework<\/h3>\n
Another sort of comment you see a lot is the excuse\/apology comment. ?I’m sure you’ve seen something like this before. ?Somewhere in a source file, you see a block comment like the following.<\/p>\n
Normally, we would never use global variables. ?It’s a bad practice, as everyone knows. ?But this past month, the business, in its infinite wisdom, decided that the report search module absolutely HAD to behave differently depending on who was logged in. ?We tried explaining to them that it would require a lot of architectural rework to allow that in a good way, and we tried to tell them about tech debt. ?But did they care? ?Of course not. ?So now we have this terrible implementation in our code, thanks to those morons in marketing.<\/p><\/blockquote>\n
Some people, including Jeff Atwood (to whom I linked earlier), hold that comments should explain “the why.” ?I understand that contention, but think it’s incomplete. ?The self-serving whining above theoretically explains “why,” but it’s pointless and worth avoiding. ?Comments explaining your rationale only make sense when you’re explaining something that a maintenance programmer has to understand in order to maintain the code. ?”I totally never normally code like this, but here’s the thing…” doesn’t qualify.<\/p>\n
TODO<\/h3>\n
Speaking of intent-related noise, I’d love to retire the TODO comment once and for all. ?I would argue that this made some sense, once upon a time. ?Or at least, it was understandable. ?IDEs even started to pick these things up and aggregate them for you, so you could work this into your planning workflow.<\/p>\n
But here’s the thing. ?We have tools explicitly made to track work items, tasks, etc. ?You can do it simply with Trello or with a more sophisticated ALM tool, like JIRA, Rally, Basecamp, etc. ?In fact, I’d be hard pressed to name all of your options. ?And these tools have also gotten really good at integrating cleverly with your code, providing traceability.<\/p>\n
Just like you shouldn’t use your code for poor man’s version control, you also shouldn’t use it for poor man’s project management.<\/p>\n
Don’t Touch This, Newbie!<\/h3>\n
I’ll close with the one that you may, perhaps, find the most controversial. ?I’m talking about the angrily-framed “here be dragons” comment.<\/p>\n
You can imagine how this develops. ?There’s a block of code in the startup logic that initializes all of the various global variables and complex event structures in an incredibly delicate balance. ?Over the years, various new team members have wandered into this code, upset the balance, and caused the senior team members days of work tracking down the issue.<\/p>\n
So what do they do? ?After a few frustrating instances, they guard the code with a giant, angry comment intended to put the fear of God into anyone happening by. ?I get it. ?But don’t do it.<\/p>\n
Similar to the end of scope comment, this style of comment represents a terrible substitute for a real solution. ?If you have a delicate, dangerous block of code that confounds newbies and invites mistakes,?fix it<\/em>. ?Or if you can’t fix it, write some form of automated test that checks for what you need, and fail the build if it fails. ?Both of those things?guarantee<\/em> that no one can break things. ?Your angry comment offers no such guarantee, offering only a window into what people might take to be a toxic team dynamic.<\/p>\n
Get the Most Out of Your Comments<\/h3>\n
The debate over whether or not to comment doesn’t figure to end anytime soon. ?Even among those who agree that you should comment, mini-debates rage about how and why. ?A big part of the reason for this results from context. ?It’s easy but incomplete to talk in abstract terms about whether or not to write comments. ?Someone saying “you can always find a way to refactor to self-documenting code” may not say that if he gets a look at what you’re looking at. ?Or the person claiming self-documenting code is a myth might not have seen your self-documenting code.<\/p>\n
With this post, I don’t aim to address commenting in general. ?I’ll even concede that you might have a situation where a TODO comment or a “don’t touch” comment really are the most elegant solution. ?I can’t possibly say that such things are?never<\/em> justified.<\/p>\n
But I can say that these things tend to represent extremely suboptimal solutions to other problems. ?Code comments shine when they help maintenance programmers achieve quick understanding and clarity. ?But if you use them for all sorts of other things, you dilute their clarifying value and solve those other problems badly. ?So as you write your comments, make sure they’re pulling their weight.<\/p>\n\n","protected":false},"excerpt":{"rendered":"
The debate over whether or not to comment your code rages on, showing no signs of stopping. ?Catalogers of anti-patterns include code comments as a code smell?because they explain problems in your code instead of fixing them. ?Not so, counter people on the other side of the aisle, sometimes angrily. ?No doubt the conversation becomes only more civil and even-keeled from there. So-called religious wars like this emerge for a variety of reasons. ?Human nature causes us to get attached to our own decisions?and to assume people making different choices than us do so as a result of personality defects. ?But in the case of code comments, even more complicating factors exist. ?One person, when speaking about code comments, may mean inline explanatory comments. Another may mean?documentation for the sake of IntelliSense. ?People will argue angrily before realizing they’re not even talking about the same thing. ?Then folks come along…<\/p>\n","protected":false},"author":4,"featured_media":392,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[2,12,14],"tags":[],"class_list":["post-394","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-articles","category-erikdietrich","category-ghostdoc"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Captain-Obvious.jpg?fit=1346%2C1717&ssl=1","yoast_head":"\nNot All Code Comments Help: What Should You Avoid? - SubMain<\/title>\n<meta name=\"description\" content=\"Wherever you fall on the spectrum of code commenting thoroughness, there are some practices with code comments that most would agree yo should avoid.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/blog.submain.com\/code-comments-avoid\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Not All Code Comments Help: What Should You Avoid? - SubMain\" \/>\n<meta property=\"og:description\" content=\"Wherever you fall on the spectrum of code commenting thoroughness, there are some practices with code comments that most would agree yo should avoid.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/blog.submain.com\/code-comments-avoid\/\" \/>\n<meta property=\"og:site_name\" content=\"Software Quality Blog - SubMain Software\" \/>\n<meta property=\"article:published_time\" content=\"2017-09-06T14:09:23+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Captain-Obvious.jpg?fit=1346%2C1717&ssl=1\" \/>\n\t<meta property=\"og:image:width\" content=\"1346\" \/>\n\t<meta property=\"og:image:height\" content=\"1717\" \/>\n<meta name=\"twitter:card\" content=\"summary\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebSite\",\"@id\":\"https:\/\/blog.submain.com\/#website\",\"url\":\"https:\/\/blog.submain.com\/\",\"name\":\"Software Quality Blog - SubMain Software\",\"description\":\"Code Quality Tools, Automated Code Review and Refactoring\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":\"https:\/\/blog.submain.com\/?s={search_term_string}\",\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"ImageObject\",\"@id\":\"https:\/\/blog.submain.com\/code-comments-avoid\/#primaryimage\",\"inLanguage\":\"en-US\",\"url\":\"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Captain-Obvious.jpg?fit=1346%2C1717&ssl=1\",\"width\":1346,\"height\":1717,\"caption\":\"Captain Obvious will tell you that there are certain comments to avoid, such as documenting the obvious.\"},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/blog.submain.com\/code-comments-avoid\/#webpage\",\"url\":\"https:\/\/blog.submain.com\/code-comments-avoid\/\",\"name\":\"Not All Code Comments Help: What Should You Avoid? - SubMain\",\"isPartOf\":{\"@id\":\"https:\/\/blog.submain.com\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/blog.submain.com\/code-comments-avoid\/#primaryimage\"},\"datePublished\":\"2017-09-06T14:09:23+00:00\",\"dateModified\":\"2017-09-06T14:09:23+00:00\",\"author\":{\"@id\":\"https:\/\/blog.submain.com\/#\/schema\/person\/cb6edf23222435414660528ab7b2fcfa\"},\"description\":\"Wherever you fall on the spectrum of code commenting thoroughness, there are some practices with code comments that most would agree yo should avoid.\",\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/blog.submain.com\/code-comments-avoid\/\"]}]},{\"@type\":\"Person\",\"@id\":\"https:\/\/blog.submain.com\/#\/schema\/person\/cb6edf23222435414660528ab7b2fcfa\",\"name\":\"Erik Dietrich\",\"image\":{\"@type\":\"ImageObject\",\"@id\":\"https:\/\/blog.submain.com\/#personlogo\",\"inLanguage\":\"en-US\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/691ca004bd18f464e9467b2f838e8fbc7a9a2c9eb8568b04a834ac653f3ab1d7?s=96&d=mm&r=g\",\"caption\":\"Erik Dietrich\"}}]}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","jetpack_shortlink":"https:\/\/wp.me\/p8R7uj-6m","jetpack_sharing_enabled":true,"jetpack-related-posts":[{"id":411,"url":"https:\/\/blog.submain.com\/code-documentation-code-comments\/","url_meta":{"origin":394,"position":0},"title":"Code Documentation and Code Comments Aren?t the Same Thing","author":"Erik Dietrich","date":"September 26, 2017","format":false,"excerpt":"Often, you hear \"code comments\" and \"code documentation\" used at least somewhat interchangeably. ?Perhaps the idea of code documentation has a little more formalism to it, in passing. ?And code comments may cover a bit less ground. But still, I hear the terms serve as synonyms for one another. ?And\u2026","rel":"","context":"In "Articles"","block_context":{"text":"Articles","link":"https:\/\/blog.submain.com\/category\/articles\/"},"img":{"alt_text":"Code documentation and code comments are different, like red and green apples.","src":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/09\/A_Red_Apple_and_A_Green_Apple.jpg?fit=1200%2C776&ssl=1&resize=350%2C200","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/09\/A_Red_Apple_and_A_Green_Apple.jpg?fit=1200%2C776&ssl=1&resize=350%2C200 1x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/09\/A_Red_Apple_and_A_Green_Apple.jpg?fit=1200%2C776&ssl=1&resize=525%2C300 1.5x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/09\/A_Red_Apple_and_A_Green_Apple.jpg?fit=1200%2C776&ssl=1&resize=700%2C400 2x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/09\/A_Red_Apple_and_A_Green_Apple.jpg?fit=1200%2C776&ssl=1&resize=1050%2C600 3x"},"classes":[]},{"id":419,"url":"https:\/\/blog.submain.com\/field-guide-code-comments\/","url_meta":{"origin":394,"position":1},"title":"A Field Guide to Code Comments","author":"Erik Dietrich","date":"October 3, 2017","format":false,"excerpt":"For someone relatively new to the field of programming, the subject of code comments would cause some definite confusion.? That's because experienced folks in the field can't seem to agree on the topic.? Some call the practice a code smell?and claim it's to be avoided.? Yet others tell you to\u2026","rel":"","context":"In "Articles"","block_context":{"text":"Articles","link":"https:\/\/blog.submain.com\/category\/articles\/"},"img":{"alt_text":"A field guide to code comments","src":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Code-Comments-Field-Guide.jpg?fit=1107%2C1200&ssl=1&resize=350%2C200","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Code-Comments-Field-Guide.jpg?fit=1107%2C1200&ssl=1&resize=350%2C200 1x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Code-Comments-Field-Guide.jpg?fit=1107%2C1200&ssl=1&resize=525%2C300 1.5x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Code-Comments-Field-Guide.jpg?fit=1107%2C1200&ssl=1&resize=700%2C400 2x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2017\/06\/Code-Comments-Field-Guide.jpg?fit=1107%2C1200&ssl=1&resize=1050%2C600 3x"},"classes":[]},{"id":670,"url":"https:\/\/blog.submain.com\/delete-commented-code-without-reading\/","url_meta":{"origin":394,"position":2},"title":"I’ll Delete Your Commented Code Without Reading It and I’m Not Sorry","author":"Erik Dietrich","date":"July 17, 2018","format":false,"excerpt":"I was knee-deep in a mess of undocumented legacy code. I wasn't even sure who had authored this code, but whoever it was, they had long departed to places unknown. The code was in a language I didn't even really know. And the bug was marked \"critical.\" If I didn't\u2026","rel":"","context":"In "Articles"","block_context":{"text":"Articles","link":"https:\/\/blog.submain.com\/category\/articles\/"},"img":{"alt_text":"finger_deleting_commented_code","src":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/07\/Finger_hitting_backspace_key.jpg?fit=1200%2C846&ssl=1&resize=350%2C200","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/07\/Finger_hitting_backspace_key.jpg?fit=1200%2C846&ssl=1&resize=350%2C200 1x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/07\/Finger_hitting_backspace_key.jpg?fit=1200%2C846&ssl=1&resize=525%2C300 1.5x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/07\/Finger_hitting_backspace_key.jpg?fit=1200%2C846&ssl=1&resize=700%2C400 2x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/07\/Finger_hitting_backspace_key.jpg?fit=1200%2C846&ssl=1&resize=1050%2C600 3x"},"classes":[]},{"id":489,"url":"https:\/\/blog.submain.com\/evaluate-code-readability\/","url_meta":{"origin":394,"position":3},"title":"How Do You Evaluate Code Readability?","author":"Erik Dietrich","date":"January 23, 2018","format":false,"excerpt":"Evaluating code readability is actually pretty easy.? I'll explain it in a way that you can easily illustrate with a flow diagram.? And you can see if you agree with my assessment. Did someone else write this code?? If so, it's not readable. Did I write this code but more\u2026","rel":"","context":"In "Articles"","block_context":{"text":"Articles","link":"https:\/\/blog.submain.com\/category\/articles\/"},"img":{"alt_text":"Code Monkey Computing Readability","src":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/01\/Code-Monkey-Computing-Readability.jpg?fit=1200%2C1133&ssl=1&resize=350%2C200","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/01\/Code-Monkey-Computing-Readability.jpg?fit=1200%2C1133&ssl=1&resize=350%2C200 1x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/01\/Code-Monkey-Computing-Readability.jpg?fit=1200%2C1133&ssl=1&resize=525%2C300 1.5x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/01\/Code-Monkey-Computing-Readability.jpg?fit=1200%2C1133&ssl=1&resize=700%2C400 2x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/01\/Code-Monkey-Computing-Readability.jpg?fit=1200%2C1133&ssl=1&resize=1050%2C600 3x"},"classes":[]},{"id":764,"url":"https:\/\/blog.submain.com\/4-reasons-need-code-comments\/","url_meta":{"origin":394,"position":4},"title":"4 Reasons Why We Need Code Comments","author":"Erik Dietrich","date":"November 13, 2018","format":false,"excerpt":"Why do we need code comments? I would not be surprised if your first answer is, \"We don't.\" I get it. Senior developer after senior developer has taught us that \"comments are bad.\" And we cheerfully nod our heads, saying, \"I am smarter for not using them.\" We grin smugly\u2026","rel":"","context":"In "Articles"","block_context":{"text":"Articles","link":"https:\/\/blog.submain.com\/category\/articles\/"},"img":{"alt_text":"You need me in code comment","src":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/11\/You-need-me-in-code-comment.png?fit=1200%2C516&ssl=1&resize=350%2C200","width":350,"height":200,"srcset":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/11\/You-need-me-in-code-comment.png?fit=1200%2C516&ssl=1&resize=350%2C200 1x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/11\/You-need-me-in-code-comment.png?fit=1200%2C516&ssl=1&resize=525%2C300 1.5x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/11\/You-need-me-in-code-comment.png?fit=1200%2C516&ssl=1&resize=700%2C400 2x, https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2018\/11\/You-need-me-in-code-comment.png?fit=1200%2C516&ssl=1&resize=1050%2C600 3x"},"classes":[]},{"id":815,"url":"https:\/\/blog.submain.com\/how-to-document-code\/","url_meta":{"origin":394,"position":5},"title":"How to Document Code: 5 Ways to Help Maintenance Programmers","author":"Erik Dietrich","date":"January 22, 2019","format":false,"excerpt":"Imagine you're a software developer working on a financial application. One day you're assigned (or, if you're agile, you pick yourself) to implement changes to the overtime computation logic so your company can sell the application in France. In France, the official work week has 35 hours (lucky them) instead\u2026","rel":"","context":"In "Articles"","block_context":{"text":"Articles","link":"https:\/\/blog.submain.com\/category\/articles\/"},"img":{"alt_text":"Maintenance_guy_with_how_to_manual","src":"https:\/\/i0.wp.com\/blog.submain.com\/wp-content\/uploads\/2019\/01\/Maintenance_guy_with_how_to_manual-838x1024.jpg?resize=350%2C200","width":350,"height":200},"classes":[]}],"_links":{"self":[{"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/posts\/394","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/comments?post=394"}],"version-history":[{"count":0,"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/posts\/394\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/media\/392"}],"wp:attachment":[{"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/media?parent=394"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/categories?post=394"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.submain.com\/wp-json\/wp\/v2\/tags?post=394"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}