Originally Posted by
digital-ether
Do you guys think inline documentation can be a good coding practice?
Especially for PHP (other "typeless" scripting languages) as you cannot explicitly declare functions and properties of a class as private/public. And you cannot specify the datatypes of variables and function returns.
Could this be an alternative to having to name variables with type information?
i comment as much as i can, but only in short bursts. when commenting how a function works, i might write a few lines, but otherwise, i just comment a couple words explaining the next block of code. i find it easier to read through a little well written code with a brief comment than a chunk of code with lot of commenting.
and usually, when variables are named with type/scope, i find i don't even have to look at commenting. when i see "strName", "objName", "and "gstrName", i know i am probably looking at the string for a name, maybe the sql results for a query regarding a name, and a global string for a name, respectively. seeing those vars named "name", "query", and "name", you can't tell scope or type.
my main gripe, not directed towards anyone specifically, is that these are basic programming 101 practices that you will be taught in any intro class when dicking around with VB6, or whatever. php shouldn't be any different, they are still variables, they still have a type, they still have a scope. just because php isn't strict about data types doesn't mean that coding principles should be more lax. indenting, naming, standards, these all effect readability and overall quality of code and lack thereof, in any other languages, are all signs of amateur coding.