Richard Bucker

commenting best practices for your favorite language

Posted at — Apr 7, 2012

I thought about reading a reddit article about NOT commenting you code.I decided not to read it because I did not want to be swayed by something that could really be meaningless drivel. But now I’m about to start a code review of a new module and I’m considering the amount of documentation I need to create and the format too.In the past I would spend hours updating javadoc in order to produce a reasonable resource. In the end it was a  very expensive effort. (1) writing it, (2) maintaing it, (3) ignoring it and reading the code anyway. And in the end all of the players would do the same.I decided to take a slightly different approach. Sadly it looks more like COBOL and python. But I think I made my point for myself:def lookup(self, lookup_key, lookup_value): “" Convert the lookup_value through a translate dict assigned to the lookup_key. “" retval = ‘' LOOKUP_DEFAULT_VALUE = ‘*' lookup_dict = self.wp[lookup_key] try: retval = lookup_dict[lookup_value] except KeyError: retval = lookup_dict[LOOKUP_DEFAULT_VALUE] return retvalExcept for the ‘wp’ variable this function should be very clear:(a) setup(b) get the translate dict instance if there is one else throw an exception(c) lookup the value in the translate dict and throw an exception if it is not there.(d) if the translate threw an exception, then try looking for a default transation(e) if the default fails, then throw the exception(off topic) In hindsight I find this funny and little ironic. As I looked at some example code in the djanjo project source tree I see that not everything is getting the benefit of the so called best practices of commenting everything. As a result I started to think about those hiring managers that read GitHub contributions. What would they think of now?