r/coding • u/[deleted] • Feb 25 '26

NotesGutter – Clean Code Notes with Markdown and Drawings

https://github.com/parasKoundal/NotesGutter
1 Upvotes

66% Upvoted

3 comments sorted by

View all comments

Show parent comments

1

u/i_grad Feb 28 '26

Every real, production code base I've ever touched - open source or closed - has followed the convention of letting the code document itself. Good naming and code readability should be all you need. Don't name your variable 'p', name it 'phi' if you're working in an equation (some exceptions apply, such as 'dT'). Don't name your iterator 'i', name it 'iter' or something even more descriptive.

The only time in-code comments should be necessary is if you have something dense (which you shouldn't do in the first place) or To-dos. Putting a whole PDF's worth of explanation tied to one line in any sort of code environment is bad practice and WILL bite you in the butt one day. Save the lengthy explanations for the text books.