I really like using the Hindley Millner Function Signature pattern, which is a byproduct of the functional programming culture.

Your comments end up succinctly representing the flow of data through the functional units of your app.

Take for example the below function that takes an array of functions and returns a single function:

// compose :: [Func] -> Func
const compose = (funcs) => {
  // Code here
  return megaFunction;
};

You can read more about it here: en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type… and here dev.stephendiehl.com/fun/006_hindley_milner.html

Beyond the above mentioned strategy, I tend to follow the pattern of whatever documentation generator I use. It depends on the language, for example, you can use YardDoc to self-document Ruby code that can be automatically parsed into a static documentation website.

You can try searching on google for "Generate documentation from comments in (Insert language here)". You should be able to find a guide that you can follow to create self-documenting code.

I add request numbers (issues logged) for fixes while doing maintenance to code. This is good practise where business rules or processes require things to be implemented a certain way

A well written code could read almost like a verbal explanation of what's happening. So, with that in mind, I try to avoid comments by reaching for a good architecture and well named structures (classes, methods, variables, etc).

Sometimes we fail to express ourselves with code. That's when we really need comments (but it should be rare!). In those cases, I try to keep them very objective (small) and close to the code it's about.

Tests are also a very good way to document your code without comments.

When adding new code to an existing method, I usually datestamp it and include my initials. I ask my team members to do the same thing. This isn't a blame thing. It's all about when it got added and who added it, just in case there's a question. Sometimes I add a brief comment about why it got added. For example:

// 08/12/2016 JLC - Need to populate this other field, too, per <whoever requested it>

There are times where I don't necessarily agree with code going in, so a reason why mitigates that and reminds me later why I did that in the first place.

sublime plugin: docblockr.

Write self-documenting code, don't write comments.

What is so bad about comments? Well, you have no proof if the comment and the code are in sync. Or you have comments which documenting the obvious. When you check in code into the repository, some statical code analysis will maybe reject your commit/push if the code is wrong but no analysis tool will reject your commit/push if the comments say nothing about the code.

Imagine this situation: Someone gets the task to update a function which currently generates two different outputs, and his task is to add a third output type. He changes the code and makes the code pass all tests. He checks in the code into the repository - but he forgot about the comment and didn't update it. Some months later a bug has been reported - an output has a wrong type, and it's your task to fix the bug. While debugging, you find this function and its old comment. The comment mentions two output types, the code clearly lists three. The bug report is about a wrong output type. What a dilemma. Have you found the correct function? Can you trust any comment now? Do you fix the bug and comment?

Don't document every code instead, document only when the code must be cryptic to achieve the desired behavior - think of C developers using ASM code to speed up this one loop. Instead, try to write self-documenting code. Here is an excellent blog post about it -> sitepoint.com/self-documenting-javascript by Jani Hartikainen

My guidlines are basically having a Document comment (JSDoc for instance for JS) as complete as possible.

I always follow this. I write comments for all the methods which I write unless it is plain save/update cases. And I advise the team to follow the same. But I make it as a habit to read their comments when I am free. If I find it plain stupid or not relevant, I asked them to change it or make it more meaningful or readable. To make sure I am doing the right thing, I ask a random developer to come and read the comment and explain to me what is the actual intent of the method.

It may sound tedious, but believe this is much needed. I used to work in maintenance project, and working with the undocumented code was horrible. That is the reason, I emphasize more on comments and I make sure my team follows it. I don't call this as a guideline, but it pretty much does what I wanted to!

This is a very good approach because it works out in small to medium to even big projects. Code review is something we take up religiously and this will give some relief for future me or us!