When to comment ?

Posted:   |  More posts about coding

One of the question we faced up when writing code is when to put comment for our code. It''s already pretty well known that we should comment on the 'why' part, not the 'how'. While looking through our code for some code review, I found these few lines of code:-

# make requests to the API and process response
resp = requests.post(url, data=json.dumps(payload), auth=auth, headers=headers)
if resp.status_code == 200:

Above I think is an example of unnecessary comment since it obvious from the code that we're making some request to a url and processing it's response. Good comment is something along this line:-

# doing POST here since the API does not yet support PUT
resp = requests.post(url, data=json.dumps(payload), auth=auth, headers=headers)
if resp.status_code == 200:

In above illustrative situation, the request logically should be a PUT request but due to some REASON it has to be a POST. The REASON that is worthy for comment since it explain the WHY part. It help the next developer coming up to maintain this code when he probably has in mental state that the request in this section of code should be a PUT not POST. The comment help him to not start raising suspicious that this section of code now has a bug.

So this just one example of when to comment our code. I'll try to add more as I encountered more examples.

Comments powered by Disqus

About me

Web developer in Malaysia. Currently work at MARIMORE Inc building internet services using Python and Django web framework.

ImportError is an error message emitted by Python when it failed to load certain module as requested by programmer. It's a very common error when someone new to the language trying it out. This website on the same theme, will try provide help for newcomers on any technologies to overcome their first hurdle.

Try most of the examples you may find here on Digital Ocean cloud service. They provide excellent VPS at a very cheaper price. Using this referral link you'll get USD10 credits upon sign up. That's enough to run single VPS with 1GB RAM for a month.


I can also be found at the following sites:-

  • http://k4ml.blogspot.com/
  • http://k4ml.github.io/
  • http://metak4ml.blogspot.com/
  • http://www.mydev.my/
  • http://github.com/k4ml/


The postings on this site are my own and don't necessarily represent my employer's positions, strategies or opinions.