Comments - Socoder

-=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- (c) WidthPadding Industries 1987 0\|296\|0 -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=- -=+=-
Socoder -> Off Topic -> Comments
Sun, 05 May 2013, 11:31
spinal	Code comments... Whats your method/style? Usually I write them as if someone might read them, but knowing full well that I’ll probably be the only one who ever reads them. I usually say things like // This is where we add the random speed, or //Guess what this does! -- How about you guys? -=-=- Check out my excellent homepage!
Sun, 05 May 2013, 11:31
Cower	Most of my comments fall into a few categories: Implementation details that aren't entirely clear at first glance. These tend to just be things like "hack," as in the following example, where the 'why' isn't immediately clear: // Hack: can't determine the aligned offset of short_data_ until it's // defined, and it'll crash the compiler if you try it, so use a dummy // type/array and get the offset from it. (see: short_data_len_) struct short_data_dummy_t { uint8_t length_; char short_data_[1]; }; enum : size_type { short_data_len_ = sizeof(long_data_t) - offsetof(short_data_dummy_t, short_data_) }; --v In that case, I had to note that the reason for the additional struct that's only needed at compile-time is because I can't determine short_data_len_ without using dummy definition to get the aligned offset of a member, because otherwise it will crash the compiler. Most people don't manage to crash their compilers, but I seem to be really good at it. Things that I might want to change later or need fixing (TODO and FIXME and FUCKME comments). Example follows. } else if (event.character >= ' ' && event.character <= '~') { // FIXME: handle non-ASCII characters u8::append(event.character, std::back_inserter(buffer_)); propagate = false; } --v Admittedly, the FUCKME variety doesn't get used very often since I have to fix those right away. Comments on what something does, mostly as a form of documentation. E.g., struct resource_parser_t : public parser_t { // Returns the resource definition and returns its kind, name, and range in // the source string as iterators. The return values may be inconsistent if // the function does not return PARSE_OK. int read_resource_def(resdef_kind_t &kind, string &name, string::iterator &start, string::iterator &end); // Reads the next definition into the given material if the next definition // is a material. If it is not a material or an error occurs, the material // may be incomplete but should be usable. int read_material(rmaterial_basic_t &material); // Reads the next definition into the program if the next definition is a // shader. If the result is not PARSE_OK, the program should be considered // incomplete and may be unusable. int read_shader(rprogram_t &program); }; --v That case is fairly simple. Just say what the function's supposed to do, the expected result, etc. This is only really needed if the result isn't obvious. For example, read_token(token_kind_t) is more or less obvious in the context of the base parser class, but how read_resource_def, read_material, and read_shader differ is pretty important since if one fails, it's not considered fatal, but if the other fails, it could crash the application. The majority are numbers two and three, since the first is usually rare enough due to my policy on avoiding code that I might ask "why did I do that?" to later. I don't mean the "why the hell did I do that, there's a way better way" but the "why did I have to do that" variety. Most comments are written from a business/royal/authorial/etc. "we" (see: nosism) rather than "I" as well, which is an odd habit that I can't explain. It just seems easier to say "we" in the context of code, probably because I'm writing it for more than one set of eyes at all times, regardless of whether it's ever actually shown to anyone else.
Sun, 05 May 2013, 13:23
rockford	I don't comment as much in my code now as I used to, but I still highlight important areas that may not make sense at a later date. The reason I don't comment as much is simply because I re-use bits of my code quite often, so I know what's what and know exactly what it does. I also know it works so I won't have to debug it later. Ha Ha - When typing that last full stop in the text above, the character kept coming up as a comma. I deleted it a few times, and repeated with full stop - it kept coming up as a comma. On the last attempt I checked it was definitely the full-stop key I pressed. Still a comma. I then wiped the screen with my finger and the comma magically turned into a full-stop now that the dirt particle was removed. D'oh!
Sun, 05 May 2013, 13:56
spinal	I almost forgot, placeholders for when I know I wont remember later what I was doing [code] Function something() ' Do first thing ' Do second thing ' Mix the two things together, or some other such thing End Function -=-=- Check out my excellent homepage!
Sun, 05 May 2013, 14:14
Cower	For placeholders, I either return a neutral value or crash the application when they're called. I will also occasionally throw this in them: void somethingUnimplemented() { #warning somethingUnimplemented() has not been implemented // Possibly call std::abort() here } --v
Sun, 05 May 2013, 14:26
9572AD	Function name Function description inputs output(s) oddity notes such as changes to globals or pointers or other bad practices date last modified I definitely write them as though someone with no idea what the code does will read them, because that person could very well be me in a year! -=-=- All the raw, animal magnetism of a rutabaga.
Sun, 05 May 2013, 14:32
steve_ancell	In my current project I've kept my comments to an absolute minimum, I learned from my last project that commenting here, there and everywhere derails me from the main task and makes me lose concentration.
Sun, 05 May 2013, 14:47
spinal	Also quite often I have old code, usually variable values or equations commented out, but kept fir future reference, usually temporary but also usually left there forever. x = 24Sin(t)/50 // 25Sin(t)/45 --v -=-=- Check out my excellent homepage!
Sun, 05 May 2013, 14:51
Jayenkai	I used to comment. My Amstrad and Amiga code is full of comments, everywhere!! Then I went to College, where I was supposed to learn how to do things properly. I learned to "writeup" my code in a "proper" manner, and inevitably gave up bothering to rewrite half the stuff as comments! That grew into a bad habit, and I've rarely commented much since then. When I do, it's usually just to remind myself why certain things have been done in a certain way, like having X function's parameter before Y, or whatever! Occasionally I'll describe a function, but only if I think someone else might use it. .. That rarely happens!! -=-=- ''Load, Next List!''
Mon, 06 May 2013, 06:01
waroffice	I tend to comment the complicated functions more, advanced or not obvious maths that sort of thing. Or if it is something new that I have not done before so I don't forget how to use it. Most comments however are to remove code I'm not sure is working or debug code function something() a=b/c*function() //does the magic // echo "stuff " + a + b + c end --v