Results 1 to 2 of 2
Thread: Documentation questions
May 18, 2012, 00:34 #1
- Join Date
- Jul 2011
- 0 Post(s)
- 0 Thread(s)
A few questions re documenting my code.
Should variable stay of the same type?
1. For example: $var = array(...), but at some point $var could be set to false. Is it good, bad practice? How would you document it? @var array || bool ?
2. A method can either return a variable, or print it. How do you handle the @return part of the documentation?
Thanks in advance
May 18, 2012, 10:26 #2
- Join Date
- Feb 2005
- Burlington, Canada
- 89 Post(s)
- 6 Thread(s)
IMHO you should never reassign variables to different types (except for some very specialized cases). It makes any sort of debugging harder.
It is ok to destroy a variable or set it to false but don't make like in your example an array to a bool.
Returning and printing are different functionalities, so if you are returning data then use @return if printing use @print
I no longer use the type of documentation that you are talking about. Instead, I primarily use TDD (Test Driven Development) with very few inline documentation. The test serve as much better documentation of how the feature set works than most documentation can do. Also, most documentation gets stale or is not consistently updated, which when needed it becomes largely useless.