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.
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.
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.
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.
You would do well to learn source control system (which these days basically means git).
Leaving aside the team/collaboration part, once you learn it, it's so incredibly freeing. I cannot understate this enough.
You can make changes to the code, and then go back with one operation (discard changes). You can work on an experimental idea (in a branch) for a few days/hours, then switch back to your main code to fix an important bug, go back and finish your experimental branch eventually, and merge everything together -- often with nearly zero effort. If you're supporting multiple release versions at once, you can fix a bug in one and often easily apply it to all other versions.
Ever have a situation where something just stops working, but you're not sure when other than in worked four months ago? You can arbitrarily check out any old version and test, and even - in a single operation - undo that change from the current version of code.
Can you do all this without source control (or with copies named by date)? Sure, but it's kind of like the difference between fetching water from a well using a hand pump and bucket vs having running water and being able to open a tap. Before you have running water, it's just life, and it's not that big a deal to fetch water, really. Once you have it, you could never imagine having to live life that way.
We used something called "Source Safe" from Microsoft.
As for what's in the Notes and deleting it upon live production... that is the old stuff... in case the new stuff stopped working for whatever reason.
I guess we all have our own methods of doing things. Fortunately, I've not had major issues, though everything is backed up to it a server upon my completion of work for the day.
The author bit is solved with version control. Much better than a line that can get bogged down with multiple authors or be outdated.
It doesn't feel like you're being old fashioned or old school. It seems like you're being a bit stubborn in your ways. Version control is a good thing. Perhaps there's better ways. Going your way with not having an sort of real alternative isn't right though.
Your other reasons like coming back years later can be applied to version control too. It's helpful to have commits that have diffs, time stamps, author, and other meta data. Imagine having to come back 3 years later without any of that. Commit history might help you remember and manage your project more quickly, efficiently, and effectively.
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.
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.
Given modern tools I’ve come to the conclusion that documenting overall purpose and specific edge cases is more than enough. For example, the file header should describe its purpose, and anything in the actual code that’s not obvious should be commented. No more boilerplate function or file comment header. Git tells me who wrote each line of code, I know the name of the funcs and files, and I can see the inputs/outputs for every func with my own two eyes.
This has always been a sign for me to tread very, very carefully. People who change code without changing the comments probably didn't read the comments, didn't read the code or didn't understand it - either way, if comment and code disagree both are probably wrong.
When I started out every function had to have a header comment, with name, inputs/outputs, description of purpose/etc. It was significant extra work to keep that up to date. I could update a function three times in a day, and have to rewrite the comments three times to check it in.
And in the end, I know the name of the function. I can see the inputs and outputs. The only part of those comments that were occasionally useful were purpose, details of which often changed with edits. And in reality, as long as the function isn't hundreds of lines long (another problem), I can read it and discern exactly what it's trying to do.
Comments that were most useful said stuff like "this looks weird or dumb, but we had to do it this way because of this thing we and you probably didn't expect in the data/system/etc"
You don't have to be a Rick to write clean, concise code.
I'd strongly recommend reading up:
http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-U...
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.
"Time Me, Gentlemen!"
https://www.theatlantic.com/health/archive/2012/10/time-me-g...
It's not hard. It's not like you're computer illiterate and don't know how to program.
None of that prevents you from using source control.
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.
/**
* 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
}
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.
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.