Sun May 19, 2019 9:04 pm
Login Register Lost Password? Contact Us


Code Documentation

Questions around writing code and queries

Mon Apr 22, 2019 4:54 pm Change Time Zone

Hello,

I was wondering if there is some good practice for code documentation in ECL. As a python programmer, I usually document my code using Doc String (google doc string) and after run doxygen, for example, to generate some nice visualization for the project.
I know that ECL uses some C/C++ comment style, so I think that applying any good practice that already is in use for C/C++ could work. However, I think that it would be nice to hear from the community if ECL already has something in place for this.

Thanks,

- Artur Baruchi
abaruchi
 
Posts: 8
Joined: Thu Apr 18, 2019 4:50 pm

Fri Apr 26, 2019 8:09 am Change Time Zone

Hi,

I asked a similar question on the availability of a 'Prittifier' for ECL.

https://hpccsystems.com/bb/viewtopic.php?f=8&t=5903

Also no replies.
Allan
 
Posts: 363
Joined: Sat Oct 01, 2011 7:26 pm

Fri Apr 26, 2019 1:03 pm Change Time Zone

Allan and Artur,

There were no replies because there are no tools we currently have for that purpose.

HPCC is Open Source. Feel free to create one and contribute it. :)

Richard
rtaylor
Community Advisory Board Member
Community Advisory Board Member
 
Posts: 1452
Joined: Wed Oct 26, 2011 7:40 pm

Fri Apr 26, 2019 1:20 pm Change Time Zone

Hi Allan,

I think there is a lack of information regarding ECL code documentation. I found an ECL best practices sometime ago (about how to name variables, code indentation, etc) that may be useful for you.
Document the code, inside the code, is one of the best practices a development team can have. I think it is faster, since you don't need to update two different places when creating new code and you can update the documentation while updating the code, so it is more accurate.

Link for doc best practices:
http://cdn.hpccsystems.com/pdf/ecl_best_practices.pdf

Thanks for replying. I will keep this thread updated as I get more information about this.

Att.
Artur Baruchi
abaruchi
 
Posts: 8
Joined: Thu Apr 18, 2019 4:50 pm

Fri Apr 26, 2019 1:46 pm Change Time Zone

Artur,
I was wondering if there is some good practice for code documentation in ECL.
ECL is already a very terse and expressive language so it is predominantly self-documenting -- meaning the code itself tells you exactly what it is doing (remember, ECL code statements are definitions, not executable code).

Because of that, you will find very few comments in our production ECL code, and the vast majority of those comments are of the "I did it this way because ..." variety.

If you look at the ECL code for things like our Date standard library (in your Repository you can find that in the ecllibrary >> std >> Date.ecl file), you can see that we do use the JavaDoc standard format to document all the code in our Standard Library. You can also adopt this practice, if you choose to.

HTH,

Richard
rtaylor
Community Advisory Board Member
Community Advisory Board Member
 
Posts: 1452
Joined: Wed Oct 26, 2011 7:40 pm


Return to Programming

Who is online

Users browsing this forum: No registered users and 2 guests

cron