Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
From the creators of devRant, Pipeless lets you power real-time personalized recommendations and activity feeds using a simple APILearn More
Clean Code Robert Martin
Or how to self document the code
Plus there are document web site builders based on the scanned code and basically comments
In python, Sphinx tool can generate documentation based on docstrings in Google style and other normal written pages in ReStructurizedText language
document _everything_ that's public. everything that's likely to be touched by someone else, or by near-future-you, or far-future-after-several-other-projects-you. code every day like you have amnesia.
don't document _what_ the code does, but _why_ it does it.
logging, logging, logging, logging, LOGGING.
let your code overflow with meaningful logging messages of all appropriate severities. i've found that, when troubleshooting unknown code, 5 lines of good logging are worth 20 lines of good code comments.
// increment i
* increment i *
Although more seriously, a comment doesn't need to explain what code is doing. It might feel useful when you're inexperienced, and that's fine, but ideally the code should be enough for that.
Comments should explain how/why code does something if its not very obvious.
You can also move a block of code into a function, then instead of having a comment that says "this bit of code does X", there's a function called "X" instead.
asgs109371y@atheist what about
/**** Comment ends here ****/
Watch some of the talks by Kevlin Henney. They give solid advice.
@asgs don't laugh until you see it in production 😂 I've seen one of the above from someone meant to be quite experienced...
h3rp1d3v5001yI just put in ticket number/issue or doc link
Use variable names that explain themselves instead of letters, numbers, and/or abbreviations. Comment if you must but don't write essays.
Read Clean Code
Document ONLY when you can’t express your intent through code.
Instead of comments:
Use meaningful variable names and method names and extract code blocks into methods like @atheist said.
Break down long call chains into multiple lines and assign intermediate values to variables which give meaning to the intermediate steps.
Don’t document just for the sake of documentation.
Don’t document based on some stupid rules like everything that is public or everything that is a method.
Automatically generated documentation is useless.
Learn to write self documenting code.
The best advice I ever had concerning documentation: you write it for **other people** who have no clue what your code does.
Always write from their perspective, not your own.
Any tips on how to properly document my code? I'm going to start my first internship soon so I need to learn it.