[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [pygame] Good code



Hi Laura

On Dec 9, 2007 6:04 PM, Laura Creighton <lac@xxxxxxxxxx> wrote:
>
> I think one of the most useful places to write comments -- and one
> which I think is rarely done -- is
>
> # hack hack hack ! this function should really do XXX instead of YYY
> # that it does now

This is a great use of comments.
In open source software, there is a casual convention like:

# XXX simplify the logic of this function

. In some games, notably *angband, this evolves into

# XXX hack: force a 'good' depth.
(in distinction from XXX - 'XXX' just meaning code that does not give
you a good feeling about how it does things, whereas 'XXX hack' is
meaning something that you know is inappropriate to do but currently
works.)

>
> That way, when you come across it later, you can be sure that
> this is code you meant to clean up and never got around to, rather
> than code that was done in this strange way on purpose.
>
> Laura
>
>