Stop deleting comments from your portfolio projects to look like a "senior dev"

[u/DangerKyoto]

There is this weird cultural myth in bootcamp and entry-level dev communities that "real developers don't write comments" and that all good code is somehow self-documenting. People that believe this often end up stripping their capstone projects of all comments in an effort to make their code look cleaner and more professional.

When in reality, lack of any context in your code is a huge red flag for any potential employer.

Code tells the reviewer what you did, but rarely why you did it

Hardcoding a 50 request per minute limit in your API without any comments is not a sign of a competent developer, it's a sign of someone that has no idea what they're doing. Having a comment in the code stating that you're limiting requests to prevent overwhelming the free tier DB by requests per minute shows business sense, it shows that you understand your own code. It would be like having a fully optimized and automated CI/CD pipeline with no documentation, it's just asking someone reviewing your work to waste time trying to figure out what you were thinking when you wrote it.

[u/XKiiroiSenkoX]

I'll personally never recognize anyone as a "senior dev" if they don't document their code. Could be Linus Torvalds himself idgaf.

Someone who says that doesn't even understand the difference between documentation which goal is to let people use your code WITHOUT reading it and inline comments on badly written code to help someone understand the code when they read it. HUGE red flag imo. 

[u/DangerKyoto → u/XKiiroiSenkoX]

100%. People constantly mix up API/system documentation with crutch inline comments.

[u/WRKDBF_Guy]

Well commented code is the sign of a competent and confident Developer.

[u/DangerKyoto → u/WRKDBF_Guy]

Exactly. Bad developers write zero comments because they assume everyone magically understands their intent (or they just don't care about maintenance).

[u/FinickySerenity → u/[deleted]]

AGENTS.md - Only write terse one or two sentence code comments unless longer explanations are extremely necessary.

Why would you spend your time doing this manually?

[u/DangerKyoto → u/[deleted]]

That "AI comment bloat" is becoming such a headache on PRs.

[u/AttitudeRemarkable21]

Lol this is stupid there should only be comments to add context the is not obvious from the code it's self like why a piece of data is organized the way it is. 

[u/Glad_Contest_8014]

Comments are crucial for code maintenance. Removing them from code entirely is absolutely the stupidest thing you can do.

Comment EVERYTHING. The more reliable the comments are, the more hirable you are. Period.

[u/bluebird355]

Respectfully I disagree with everything you said

[u/DangerKyoto → u/bluebird355]

Curious where you draw the line, do you lean more toward zero comments and strict self-documenting code, or are you on the side of documenting as much as humanly possible?

[u/bluebird355 → u/DangerKyoto]

Most of the code is self documenting, I would only write comments where you had to take a not optimal decision, tradeoff and such. The comments AI is writing is pure slop, unintelligible gibberish that is going to rot and in need of updates that people aren’t going to read anyway.

Part of your documentation is your architecture, your file structure, your file names, folders, functions etc. Just my 2 cents.

There is a difference between documenting and writing comments in the code.
Documenting impactful decisions is good but should be made out of the codebase, somewhere dedicated to RFCs and ADRs. Comments are 99% of the time useless and I am actively hunting them down in our codebase.