Students in introductory programming courses sometimes feel, “What’s the use in commenting? The important part is getting the program to run.” Some students also feel, “Adding too many comments clutters the code.” As a result, there’s a tendency to avoid commenting or to do the minimum required.<\/p>\n
Commenting, however, is a vital part of programming, as commenting is what makes your code useful to others (including yourself a month later). If you don’t comment your code, no one else can pick up your code and understand it. Think of it this way. If a company hires you to write some code and you leave the company after writing it, if you didn’t comment your code, how will your replacement understand what you did? And if your replacement has to rewrite your code because no one can understand it, didn’t your company just waste its money on your salary? As a result, no software development company will let someone contribute code that is poorly documented.<\/p>\n
That being said, I admit you can overcomment. Especially when we’re first learning how to comment, we will tend to provide more details than are necessary. Still, if you’re just starting to learn how to program, I’d encourage you to overcomment rather than undercomment. At this stage, you need to get into the habit<\/i> of writing comments. At this stage, the only way to do so is to write more than less. As you gain more experience in programming, you’ll get a better sense of what needs to be included and what doesn’t. But you can’t get to that stage if you scrimp on commenting now.<\/p>\n
It’s like learning to write essays. As a second-grader, when your teacher asked you to write about your favorite pet or what you did over Spring Break, they didn’t say, “make sure you only use active voice and be as concise as possible.” No, they just wanted you to write as much as you could. Only later in school did your teachers say, “be concise, etc.” The same thing is true with comments. At this point, you need to create the habit of commenting, even if you don’t want to and feel it’s a waste of time. Describe what goes into a method, what comes out, the state of the program going in, the state coming out, and what gets changed and how. If you feel you’re saying too much, that’s okay. Later on, you’ll learn about what to leave out.<\/p>\n","protected":false},"excerpt":{"rendered":"
Students in introductory programming courses sometimes feel, “What’s the use in commenting? The important part is getting the program to run.” Some students also feel, “Adding too many comments clutters the code.” As a result, there’s a tendency to avoid commenting or to do the minimum required. Commenting, however, is a vital part of programming, […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[5],"tags":[],"class_list":["post-92","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=\/wp\/v2\/posts\/92","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=92"}],"version-history":[{"count":5,"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=\/wp\/v2\/posts\/92\/revisions"}],"predecessor-version":[{"id":97,"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=\/wp\/v2\/posts\/92\/revisions\/97"}],"wp:attachment":[{"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=92"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=92"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.johnny-lin.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=92"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}