4 ms·

> 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 th

> 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.
  - mattbgates 9y ago
    Well, I'm glad you don't have to go into my code to see that sloppy tabbed mess full of comments and code :)
- sverhagen 9y ago
  "Old school"? I think it's in most cases irresponsible not to use version control. Sorry to say, but it's "amateur hour". No better than "Rick". I agree with one of the parents that "Purpose" is probably the most useful, but even there: at that level the code should be largely self-documenting.
  - mattbgates 9y ago
    I never said I didn't have version control. To assume "at the code level it should be largely self-documenting" is to be a Rick. Comments are there to help everyone, including non-programmers understand what is going on.
    - skinnymuch 9y ago
      You said initially companies have their tools and you don't. Later you went on about simply using ftp and coding php. It sure seems like you don't use version control. At least not at a level that it should be used at in this day and age.
    - sverhagen 9y ago
      What am I to make from: "while I know companies use tools to do their thing... I don't", if not that you're not using a version control tool? It's not "genius behavior", but well accepted from people like Uncle Bob, that documentation should be in the names of small and focused functions, methods or classes, not in comments.
account193 9y ago
I will have to admit that this GIT/SVN is a very elegant solution in the ideal world, but in my experience real world code gets very very messy. Teams get lazy and don't always give very detailed commenting in version control. Startups may be better at this, but the corporate world is even messier with quick turned spaghetti code. Any markup in the codebase itself helps the next developer tremendously. Personally, I find @mattbgates best practice to be very justifiable in practical use.

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.
- mattbgates 9y ago
  Well, I'm glad you don't have to go into my code to see that sloppy tabbed mess full of comments and code :)
sverhagen 9y ago
"Old school"? I think it's in most cases irresponsible not to use version control. Sorry to say, but it's "amateur hour". No better than "Rick". I agree with one of the parents that "Purpose" is probably the most useful, but even there: at that level the code should be largely self-documenting.
- mattbgates 9y ago
  I never said I didn't have version control. To assume "at the code level it should be largely self-documenting" is to be a Rick. Comments are there to help everyone, including non-programmers understand what is going on.
  - skinnymuch 9y ago
    You said initially companies have their tools and you don't. Later you went on about simply using ftp and coding php. It sure seems like you don't use version control. At least not at a level that it should be used at in this day and age.
  - sverhagen 9y ago
    What am I to make from: "while I know companies use tools to do their thing... I don't", if not that you're not using a version control tool? It's not "genius behavior", but well accepted from people like Uncle Bob, that documentation should be in the names of small and focused functions, methods or classes, not in comments.

account193 9y ago

I will have to admit that this GIT/SVN is a very elegant solution in the ideal world, but in my experience real world code gets very very messy. Teams get lazy and don't always give very detailed commenting in version control. Startups may be better at this, but the corporate world is even messier with quick turned spaghetti code. Any markup in the codebase itself helps the next developer tremendously. Personally, I find @mattbgates best practice to be very justifiable in practical use.