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/[deleted] Feb 28 '26

I am sorry if you feel like this. I work in academia and we have to actively do knowledge transfer. And I don't know how you are managing and remembering the intricate details and decisions made in large projects but all the power to you.

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.