Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[MorleyDev]

I don't like writing what code does in comments. That's what the code is for. If I want to know what a function does and can't tell by it's name, that's what the unit tests are for. If I can't understand either of those, it's very unlikely a comment would of helped clarify things any better.

A "Why I did this" comment can be useful, especially when doing browser dev. You know, "Works around bug in IE8 where this outdated browser insists on remaining a pile of horse plop", that kinda thing (Bloody enterprise clients, some of them still insist on supporting IE6).

[Ghills]

same here, no comments

if the code smells so much you're tempted to comment it, move it to it's own method until it became clear and name the method as you would explain the operation in the comment.



above all thing, all developers should read code complete.

Code should be the 'what' sure - as in, 'what does this do' - but comments are needed for 'why did we do this/do this this way', 'how and where this function is used', 'when this was added', 'who added it', etc.  Only one of the fundamental questions can be answered by code, regardless of how clear the code is.

[Ghills]

I don't like writing what code does in comments. That's what the code is for. If I want to know what a function does and can't tell by it's name, that's what the unit tests are for. If I can't understand either of those, it's very unlikely a comment would of helped clarify things any better.

A "Why I did this" comment can be useful, especially when doing browser dev. You know, "Works around bug in IE8 where this outdated browser insists on remaining a pile of horse plop", that kinda thing (Bloody enterprise clients, some of them still insist on supporting IE6).

'What this does' comments can be useful as a brief refresher when coming back to a project or introducing a new coworker to the code.  They save a lot of time vs reading code that was written by someone else 6 months ago and has left the team since.

[Skyrunner]

same here, no comments

if the code smells so much you're tempted to comment it, move it to it's own method until it became clear and name the method as you would explain the operation in the comment.



above all thing, all developers should read code complete.

Code should be the 'what' sure - as in, 'what does this do' - but comments are needed for 'why did we do this/do this this way', 'how and where this function is used', 'when this was added', 'who added it', etc.  Only one of the fundamental questions can be answered by code, regardless of how clear the code is.

Minor disagreement. I think 'who added it' and 'when this was added' shouldn't be handled by comments but rather by version control software, like git.

[Antsan]

but comments are needed for 'why did we do this/do this this way', 'how and where this function is used'

Especially the second one suffers from severe code rot, which should be provided by editor/IDE features and documentation, not by comments.

[LoSboccacc]

but comments are needed for 'why did we do this/do this this way', 'how and where this function is used'

Especially the second one suffers from severe code rot, which should be provided by editor/IDE features and documentation, not by comments.

however, if it is part of a library, document the heck out of it. throw exception early for any wrong input, document the exception, and put a relevant message in the exception (sorry I'm just a lot salty about our current platform)

[LoSboccacc]

so, I learned LUA today and having a blast programming missile guidance system for a videogame (From the Depths)

have a look!

probabilistic guidance: shoot a cloud of missiles around the target possible future position and let the target slam into one of them -  https://www.youtube.com/watch?v=0eTGJraqANw

javelin guidance: cilmb to 100mt above the target and tries to hit it from the vertical to avoid the citadel armor - https://www.youtube.com/watch?v=BbYnRUo40EY

[Putnam]

Lua's a name, not an acronym!

Anyway, yeah, Lua's really good for scripting stuff. I made a homing missile system in Super Metroid using lua-script memory hacking, but it's simple as hell: it sets the missile's acceleration vector (a byte in the projectile's memory that sets whether it's moving up, down, left, right or some diagonal, there's some overlap in there) based on the position of the nearest enemy (going diagonal unless the enemy is directly in a cardinal direction). It works surprisingly well. Interestingly enough, each projectile has a different acceleration speed; missiles are the most reliable at homing since they accelerate fairly quickly (but not too quickly!), super missiles go too fast to be reliable (they tend to overshoot) and beams can't really turn around.

https://gfycat.com/DentalBlackLadybug

[itisnotlogical]

Though I'm still not convinced that comments are totally bad, I do notice myself using them less often as I develop my skills more.

[Calidovi]

Though I'm still not convinced that comments are totally bad, I do notice myself using them less often as I develop my skills more.

I spam comments because I have a horrible memory and am poor at recognizing the purpose of most of the functions I put in.

[MorleyDev]

Code should be the 'what' sure - as in, 'what does this do' - but comments are needed for 'why did we do this/do this this way', 'how and where this function is used', 'when this was added', 'who added it', etc.  Only one of the fundamental questions can be answered by code, regardless of how clear the code is.

I'm of the mind that how and where are better addressed via Unit Tests (demonstrating the how) and "Find Usages" (to find the where), and a good code structure that breaks things down into collected set of namespaces that naturally build upon each other (to indicate the where it goes, the intent behind those namespaces may need to go in comments or documentation though).

I do tend to write more thorough comments when not also writing unit tests and specification tests and such, but in my mind that's me trying to compensate for the lack of having time to do it the 'proper way'

And yeah, When and Who are surely source control concerns? git blame and svn blame. Kinda dislike the names of those (you aren't blaming anyone! That word has negative connotations! Negative!), but they are useful when you need to know who did a thing and when. Back and before the VSS legacy project days, "Who and When" comments had more purpose though, and I've had to crack open a legacy project or two in my time.

Which is how I view commenting: It's a fallback for when your tools and process are currently limiting your capacity to do things the 'proper way' due to time or technology constraints. Deadlines gonna deadline and managements gonna management, and some tools just don't allow you to encode things effectively in the code or the tool.

[miauw62]

Though I'm still not convinced that comments are totally bad, I do notice myself using them less often as I develop my skills more.

comments are really important imo, a big thing is just understanding when to comment and when not to comment.

[i2amroy]

Though I'm still not convinced that comments are totally bad, I do notice myself using them less often as I develop my skills more.

comments are really important imo, a big thing is just understanding when to comment and when not to comment.

Indeed, a factor that involves a fair bit more than just what you are doing in any sort of real project, but also factors in things like how many people are expected to interact with that particular bit in the lifetime of your code, their expected skill levels, and so forth.

I'm certainly going to do more comments on an open source project with 300+ contributors like Cataclysm: DDA than I am on a project only for my own personal use.

[Reelya]

Though I'm still not convinced that comments are totally bad, I do notice myself using them less often as I develop my skills more.

comments are really important imo, a big thing is just understanding when to comment and when not to comment.

It's a good reason to use full English names for functions and variables. For example a function like DistanceSquared(vector, vector) really doesn't need a comment, but if you were lazy and called it "d2" it would need a comment. But someone who saw "d2(a,b)" in your code somewhere might have to backtrack to the function declaration to read that comment, which kinda sucks.

With auto-complete in modern IDEs there's basically no excuse not to use fully descriptive names everywhere. It just makes the code easier to read and needs less comments.

[Telgin]

That is exactly why I hate working with old Fortran code.  Probably new Fortran code too for that matter, or any scientific code.  I guess I can understand that it's annoying to write "first_derivative_of_x(i, j)" a hundred times, but at the same time I really hate having to scan a source file for a comment to explain what the variable "wsct0(i, j)" means.  If there's a comment at all.