Hot take: A friend told me my code was 'unreadable' and it made me switch how I write comments.

I was working on a small weather app project last month and showed my code to a friend who's been programming for a few years. He looked at it for a minute and said, 'Dude, I have no idea what this function does. It's just a wall of text.' I had written maybe two comments in the whole file, thinking the code spoke for itself. He told me to try writing a comment for every single function, even the simple ones, explaining what it does in plain English. At first I thought it was a waste of time, but I tried it on my next bit of code. I wrote stuff like 'this function converts Celsius to Fahrenheit' right above it. Coming back to it a week later, I could actually follow my own work. It felt slower to write, but saved me so much time fixing things. Now I'm torn because some people online say too many comments are bad and the code should be clear on its own. What's the better rule for a beginner: comment everything, or try to write super clear code with almost no comments?

2 comments

2 Comments

reese_patel13d ago

Ever hear the phrase "code for your future self"? Comment the WHY, not the what.

jason75213d ago

Wait, you changed your whole style over one comment from a friend? I get what @reese_patel says about the why, but isn't writing a novel for every simple function just overkill?