6 ms·

I think I have to agree with you. The fact that Rick was allowed to be turned from a Dr. Jekyll to a Mr. Hyde is kind of the company's fault. No one stepped in

I think I have to agree with you. The fact that Rick was allowed to be turned from a Dr. Jekyll to a Mr. Hyde is kind of the company's fault. No one stepped in to hold Rick accountable during meetings? While I no longer work there, my first job with some programming had me training to understand the code, what it was about, and even how to write it. To this day, I still use this method so I don't get lost or bored in my code. These are the lines I actually use along with commenting my own code just in case I have to return back to it weeks or months or even years later, I don't have to try and trace every step back to a particular code. // AUTHOR: MG // FILENAME: functions.php // STATUS: ACTIVE // PURPOSE: All of the functions for this application (app name) // NOTES: There are several unused functions in this file that are commented out but once in production // They can be deleted as we likely will not be needing them at all. Those 5 lines have saved me a lot of time. While I don't include the "author" line since it just me writing the code, if there are tons of hands in there, you should know EVERY SINGLE author as well as when code gets commented, it should contain the initials upfront, such as // mg: this does this and this does that. If I know multiple files touch.. I also add: "ASSOCIATIONS:" and list all files that call this one. Using this method, I've been able to complete a bunch of projects much quicker because any time I start to forget: what am I doing? what does this code do? am I on the right track? I can look right at the beginning of a file and know the answer. I'm not saying that a boss or supervisor has to be a micromanager, but meetings are necessary to understand where everyone is at. Leaving a programmer to do his own thing means that he really is doing his own thing and is more likely to get lost in the code. I'd say more like he wasn't a genius but thought he could do it alone.. and sometimes, it is nice to have someone step in and tell you: "Hey where we at? What can we do to speed this up?" or even provide their own insight... I can't tell you how many times I've talked with my spouse about an issue.. and she's suggested, "Why don't you just do this?" and it has saved me hours of time just because of someone not in the code is able to see another solution.

Avalaxy 9y ago
> AUTHOR: MG This is already in your commit history, so why hardcode it into the source? > FILENAME: functions.php This is obvious because you just opened the file. So again, why even put it there? When the file gets renamed the documentation is no longer correct? These things are also hard to refactor. > STATUS: ACTIVE Every part of the code is always active... > PURPOSE: All of the functions for this application (app name) Okay, probably the most useful one here. But what if we're refactoring the code and the purpose changes? Or if someone adds a few functions and the documentation no longer covers the purpose? > NOTES: There are several unused functions in this file that are commented out but once in production They can be deleted as we likely will not be needing them at all. Very dangerous, again because the source might change while the documentation doesn't. But why even write "they can be deleted"? Why not just delete them? That's what version control is for.
- nowbacktowork 9y ago
  I'm not sure why you're being down voted, but this is a very reasonable counter point. The purpose or brief should be at the top of every file, it should also evolve as class or implementation does. Arguable that it's really the only one that matters and can also come from no other tool or location.
- mattbgates 9y ago
  Avalaxy, while I know companies use tools to do their thing... I don't, I'm old school. I have files on an FTP server and I write PHP code. But to explain: > Author: completely optional, depends on what you are using, you aren't wrong.. since I'm old fashioned, if I were to hire some coder to help me maintain my programs, I'd like to know that he was in there, and I'd have no way of knowing.. again, probably not anyone's issue, but I'm old fashion. > Status: Not all files are in use, but sometimes they are just leftover and may not be deleted, or sometimes, they might be used for testing purposes -- so Status can be changed to INACTIVE, TESTING PURPOSES ONLY, etc. Maybe the file is inactive because newer code was written, but this was kept as an archive? You never know. > Purpose: always state the purpose of the code.. if it changes, than this should probably change. If it doesn't, than again: you must be doing your own thing. > Notes: optional, this is just notes that might be necessary..... again.. Notes to myself: I have some code in there that is not currently being used and if I go into production, I probably won't need it so may as well delete it. The Notes weren't supposed to be taken as a literal. This is just notes to anyone who reads the file. Sure, there is a such thing as too much commenting, but no one wants to go through the code to figure out what it does. Leaving a little comment up top of every page, regardless of the simplicity or complications of the function, it is just nice to leave for anyone who has to go in there. It's a better form of organization. Imagine having to go in there 3 years later... would you remember what it does? The little statement up top might help you remember more quickly.
  - no29 9y ago
    rcs has been around ~40 years. you're not old school. you're sloppy.
GuB-42 9y ago
Why don't you use source control instead. Don't say who you are in the comments, that's what "blame" is for. Don't comment code, delete it, it won't be lost since you have a history. Make a branch for your experiments if you have to. The state of your work should be apparent in the bugtracker. Code comments are code comments. If you use comments to help with your development process, there is probably some work to do with your toolchain. Good source control and a bugtracker are a must.
scintill76 9y ago
Reminds me of this style: /** * Calculate the thing. * * @param $foo the foo value * @param $bar the bar value * @return the thing */ function calculateThing($foo, $bar) { return $foo + $bar; // add foo and bar } Such comments are worthless noise that obscures the important parts of the code and camouflages any actual useful comments that might be there. I would so much rather have better names than "thing", "foo", and "bar", and maybe a comment about why the values are summed, if it's not obvious. When you do those right, you won't even need many comments. Maybe a docblock, but don't bother with that if it's nothing more than a robotic "English version" of what is already obvious from the function definition. IMO most good developers will perceive your file header as a redundant annoyance for similar reasons, as other commentors have explained.
- pc86 9y ago
  It's the "CS 050 Computer Science for Humanities Majors" type of commenting (I was a humanities major, no offense intended). A bunch of comments that are only there because you think you have to have comments, or because you're graded on whether or not comments exist.

Avalaxy 9y ago

> AUTHOR: MG This is already in your commit history, so why hardcode it into the source? > FILENAME: functions.php This is obvious because you just opened the file. So again, why even put it there? When the file gets renamed the documentation is no longer correct? These things are also hard to refactor. > STATUS: ACTIVE Every part of the code is always active... > PURPOSE: All of the functions for this application (app name) Okay, probably the most useful one here. But what if we're refactoring the code and the purpose changes? Or if someone adds a few functions and the documentation no longer covers the purpose? > NOTES: There are several unused functions in this file that are commented out but once in production They can be deleted as we likely will not be needing them at all. Very dangerous, again because the source might change while the documentation doesn't. But why even write "they can be deleted"? Why not just delete them? That's what version control is for.

nowbacktowork 9y ago
I'm not sure why you're being down voted, but this is a very reasonable counter point. The purpose or brief should be at the top of every file, it should also evolve as class or implementation does. Arguable that it's really the only one that matters and can also come from no other tool or location.
mattbgates 9y ago
Avalaxy, while I know companies use tools to do their thing... I don't, I'm old school. I have files on an FTP server and I write PHP code. But to explain: > Author: completely optional, depends on what you are using, you aren't wrong.. since I'm old fashioned, if I were to hire some coder to help me maintain my programs, I'd like to know that he was in there, and I'd have no way of knowing.. again, probably not anyone's issue, but I'm old fashion. > Status: Not all files are in use, but sometimes they are just leftover and may not be deleted, or sometimes, they might be used for testing purposes -- so Status can be changed to INACTIVE, TESTING PURPOSES ONLY, etc. Maybe the file is inactive because newer code was written, but this was kept as an archive? You never know. > Purpose: always state the purpose of the code.. if it changes, than this should probably change. If it doesn't, than again: you must be doing your own thing. > Notes: optional, this is just notes that might be necessary..... again.. Notes to myself: I have some code in there that is not currently being used and if I go into production, I probably won't need it so may as well delete it. The Notes weren't supposed to be taken as a literal. This is just notes to anyone who reads the file. Sure, there is a such thing as too much commenting, but no one wants to go through the code to figure out what it does. Leaving a little comment up top of every page, regardless of the simplicity or complications of the function, it is just nice to leave for anyone who has to go in there. It's a better form of organization. Imagine having to go in there 3 years later... would you remember what it does? The little statement up top might help you remember more quickly.
- no29 9y ago
  rcs has been around ~40 years. you're not old school. you're sloppy.

GuB-42 9y ago

Why don't you use source control instead. Don't say who you are in the comments, that's what "blame" is for. Don't comment code, delete it, it won't be lost since you have a history. Make a branch for your experiments if you have to. The state of your work should be apparent in the bugtracker. Code comments are code comments. If you use comments to help with your development process, there is probably some work to do with your toolchain. Good source control and a bugtracker are a must.

scintill76 9y ago

Reminds me of this style: /** * Calculate the thing. * * @param $foo the foo value * @param $bar the bar value * @return the thing */ function calculateThing($foo, $bar) { return $foo + $bar; // add foo and bar } Such comments are worthless noise that obscures the important parts of the code and camouflages any actual useful comments that might be there. I would so much rather have better names than "thing", "foo", and "bar", and maybe a comment about why the values are summed, if it's not obvious. When you do those right, you won't even need many comments. Maybe a docblock, but don't bother with that if it's nothing more than a robotic "English version" of what is already obvious from the function definition. IMO most good developers will perceive your file header as a redundant annoyance for similar reasons, as other commentors have explained.

pc86 9y ago
It's the "CS 050 Computer Science for Humanities Majors" type of commenting (I was a humanities major, no offense intended). A bunch of comments that are only there because you think you have to have comments, or because you're graded on whether or not comments exist.