On Thu, Jun 30, 2011 at 4:18 PM, Douglas Hubler <[email protected]> wrote:
> I am struggling trying to figure out how to use the location manager
> api in sipxconfig. I'm am a firm believer in self documenting code,
> but after the code has been simplified as much as possible, adding
> comments makes a lot of sense. I'm as guilty as anyone else for not
> documenting, but I now have a renewed sense.
>
> So I'm not necessarily looking for "yeah, i agree, we should make an
> effort to document our code more" because i suspect we'd all have the
> comment. I'm more looking for :
> * war stories from people about how they suffered learning the code
> because of the lack of comments
>
IMO the ugliest code is the code that doesn't have any comment. In Java
world, UML class diagram generation may help
understand the whole picture. If the developer created nice names for
methods, variables may also help understanding the code
I am 100% against variable names like: button1, button2, var1, var2 etc...
> * notes from folks they had the same ideas as me, but just didn't bring it
> up
> * comments that you disagree
>
I don't like when somebody say in their code: try/catch{//nothing to do} or
//it should work
//avoid NPE etc...
I don't like long methods that contain commented code. IMO, commented code
should be deleted
> * ideas on how to motivate developers to comment their code.
>
previous sufferings during reading uncommented code can make you more
disciplined in commenting personal code :)
>
> If if get enough positive feedback, one idea i had was to publish the
> javadocs to sipfoundry on an automated basis so we have a canonical
> location to reference.
> _______________________________________________
> sipx-dev mailing list
> [email protected]
> List Archive: http://list.sipfoundry.org/archive/sipx-dev/
>
_______________________________________________
sipx-dev mailing list
[email protected]
List Archive: http://list.sipfoundry.org/archive/sipx-dev/
