{"id":78659,"date":"2018-05-05T14:41:49","date_gmt":"2018-05-05T14:41:49","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=78659"},"modified":"2019-01-22T17:14:59","modified_gmt":"2019-01-22T17:14:59","slug":"who-comments-code","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/blogs\/who-comments-code\/","title":{"rendered":"Who comments code?"},"content":{"rendered":"<p>I am a firm advocate of commenting code, but you need to make sure that you are commenting the right thing.\u00a0 I worked on a project last year and then the project was paused.\u00a0 I\u2019m now back on it full time, some 6 months later. \u00a0I wrote most of the database code and all calls from the application to the database are via stored procedures.\u00a0 All stored procedures have code headers that include:<\/p>\n<ul>\n<li>Description<\/li>\n<li>Used by<\/li>\n<li>Sample execution<\/li>\n<\/ul>\n<p>and then a table showing:<\/p>\n<p>Date, modified by, and reason<\/p>\n<p>Also, all the different aspects of the code have a comment block on why it\u2019s doing what it\u2019s doing.<\/p>\n<p>However, after 6 months and after commenting extensively, or so I thought, I still have no idea why I did half the things I did.<\/p>\n<p>I\u2019m now thinking that my code header should include a list of what the code needs to do, or maybe it\u2019s just that my descriptions need a lot more information.<\/p>\n<p>What I have discovered though is that whilst I do comment I need to do an awful lot more.<\/p>\n<p>I&#8217;d be very interested to people&#8217;s thoughts on this.\u00a0<\/p>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I am a firm advocate of commenting code, but you need to make sure that you are commenting the right thing.\u00a0 I worked on a project last year and then the project was paused.\u00a0 I\u2019m now back on it full time, some 6 months later. \u00a0I wrote most of the database code and all calls&#8230;&hellip;<\/p>\n","protected":false},"author":10747,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[2],"tags":[5134],"coauthors":[57570],"class_list":["post-78659","post","type-post","status-publish","format-standard","hentry","category-blogs","tag-sql-prompt"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/78659","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/10747"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=78659"}],"version-history":[{"count":4,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/78659\/revisions"}],"predecessor-version":[{"id":78801,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/78659\/revisions\/78801"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=78659"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=78659"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=78659"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=78659"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}