SitePoint Sponsor

User Tag List

Results 1 to 2 of 2
  1. #1
    SitePoint Zealot
    Join Date
    Jul 2011
    Posts
    199
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    Documentation questions

    Hello,

    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

  2. #2
    Foozle Reducer ServerStorm's Avatar
    Join Date
    Feb 2005
    Location
    Burlington, Canada
    Posts
    2,699
    Mentioned
    89 Post(s)
    Tagged
    6 Thread(s)
    Hi,

    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.

    Regards,
    Steve
    ictus==""


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •