Re: [Tuxpaint-devel] Well organized and commented code of my animation application

[Mark K. K. <mkk...@gm...>]

On Wed, Apr 16, 2008 at 08:52:54PM +0530, Ajay Kumar wrote:
>     I have taken some time out of my final exams preparation time and have
>    edited my code. Now i have my code in a well organized manner and is
>    commented to the possible extent. The commented code is uploaded here.
>    [1]http://www.uploadcomet.com/download.php?file=6b7e2d553a76f09fca38eafba762e0c6.

Ajay,

I skimmed through your code and have some bad news.  I'm not very
confident in your coding skills after having read through your source
codes.  Here is some feedback to help you improve your coding style:

1. There are too many comments.  You were right about earlier - the code
   should be self-documenting as much as possible and contain just
   enough comments where clarification is needed.
   
   Also, this is not as critical, but all things being equal the
   comments should adhere to the standard C comments using /* ... */
   rather than the C++-style (a.k.a.  BCPL-style) comments.  This is to
   be compatible with older compilers on non-standard platforms whenever
   possible.  This depends on your target platforms, however.

2. Indentations are inconsistent and incomprehensible.  Some
   indentations are 0 spaces while I've found a location with 25 spaces
   (not tabs that result in 25 spaces) as the indentation.  I also found
   a place that had 2 space indentation at the opening bracket but 5
   space indentation at the closing bracket, which is misleading.  This
   is not only irregular (which would be a minor annoyance) but this
   makes code hard to read and bug-prone.

   This is a huge problem that should be obvious from the beginning.

3. Header files contain functions!  Header files should not contain
   functions (except macros, and also inline functions and templates
   when writing C++ codes) but the functions should be included in
   separate .c files.  The header files should contains appropriate
   multi-C file 

   This is an important concept to understand, but probably not
   something you'd be expected to know at this point in your career so I
   wouldn't count it against you, though.

4. The main function is too long.  It should be broken down to smaller
   functions if possible.  (Tux Paint, however, also suffers from the
   same problem, a problem I hope will be corrected sometime in the
   future.)

5. You shouldn't need to add comments or clean up the code for us.  The
   code you write on a daily basis should stay relatively clean most of
   the time and fairly presentable without much modification.  It
   appears you made a lot of effort to add all these comments which
   troubles me, because it shows the code you normally write is not very
   clean and requires a lot of work to clean up.

However, do not take my comments too critically at this point in your
career.  I would not expect you to be able to know or do any of the
above with expertise at this point in your career juncture as a
university student EXCEPT #2.  #2 should be fairly obvious even to a
beginning programming student and I would expect a decent programmer at
a university program to have made at least some effort to correct them
while one was writing the code.  Codes without decent indenting often
create buggy and hard to read code and that will harm a project more
than help it.

I'm not sure if I'll be able to help you here.  Other mentors may feel
differently but I'm afraid I cannot endorse your application this year.
I hope you improve your coding skills and apply again next year.

Regards,

-Mark