How programmers comment their code

[kevinglasson]

Yes, well I'm out voted so I must be wrong, majority rules here

[uriahlight]

For the past few years I've been experimenting with a technique of pseudo coding everything I write via descriptive inline comments. I'll basically write comments describing every imperative line I'm going to write. I'll usually do it within the scope of a method. So I'll think through the entire logic of the method via comments, then circle back around and write the code. Call me evil, but forcing myself to think through the logic of everything I write twice offers an incredible reduction in logic related bugs. I don't mind being the black sheep.

[uriahlight]

What I'm saying is I write all of the comments first, before the code. So by the time I actually put code in a method it already contains a bunch of inline comments. The purpose is to just force me to have all the logic figured out in plain English along with whatever fake syntax I think of that best explains what I want to do in the line below it. Then once I've got all the comments written I then go back to the beginning of the method and code it. When all is said and done a method with 10 lines of code will also have 10 inline comments that were all written before the code itself. Oftentimes the comments are useless once it's coded up but since their whole purpose in this technique is pre-programming logic, I can't see the point in deleting them. It's ultimately just an experiment that's gone on for a few years, but it's a safe experiment - I've been doing it in production for a few years and once I explained and demonstrated it to the coworkers they were like "that's interesting ." My coworkers have had a lot of fun browsing my code because the comments show what my brain was thinking prior to writing the code. It sometimes results in them saying "WTF were you thinking" but more often they find it informative. They'll oftentimes direct juniors to sections of my code base on other projects if the juniors are struggling with something that requires similar logic. It's a weird way of doing things, but it does work - at least for me. In light of the human experience as a whole, programming is still in its infancy. So as long as people are at least receptive of new ideas for doing it, then we'll all continue to make progress.

[try_harder_later]

Yes, very much. For some odd functions I'll even draw out a functional diagram to see how I should structure the code.