• 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
How do you comment sections in classes?

#1
[eluser]xwero[/eluser]
In a contribution thread i asked how the EL developers would create sections in a class based on comments. Docbook doesn't provide a way to format section comments so it's up to us to come up with a format.

First i give you a CI class that could be more clear with sections; the Form_validation library. Its methods fall into three sections:

- process validation : run, _execute, set_rules, ...
- rules : required, ...
- output : error, error_string, set_value, ...

In the current library the process validation and output section methods are mixed, because the developers didn't see the context of the methods?

But the main question here is how would you add the section header comment?
Personally i like this
Code:
// ----------------------- CIs way to create a more visible end for functions

// #######################
// section name
// #######################

/**
* function comment         Docbook
*/
The pound sign gives an in you face marking but it's gone in the documentation specifications for reasons unknown to me. So i mixed it with the double forward slash, one line, comment format.
The contribution i mentioned before made really fat section names.

What are the alternatives? Or can anyone explain why sections in classes are a bad idea?


Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  


  Theme © 2014 iAndrew  
Powered By MyBB, © 2002-2020 MyBB Group.