Clean up library and document it more consistently

[kbabioch]

I really like the effort you are putting into this library. The results look amazing and it seems that you are the only game in town when it comes to filtering DCF77 data in a sophisticated way. However, I think the "packaging" of the library might be improved in several ways, to make the library more attractive:

• First of all the source should be split into a couple modules. Right now everything resides in a single file, which is somewhat of 3000+ lines of code. Splitting it into several modules would make it more easy to get an overview and maintain the code.
• Although there are quite a few comments describing specific steps, personally I miss more general comments describing the functions itself. I think Doxygen might be a great option for this.
• Make the library more generic: I don't see any Arduino specific stuff within the source code, so I don't see a reason why the README is referring to this as an Arduino library. In my book it should be usable for pretty much any AVR. Maybe it could be made even more generic with some additional options, so that other devices (PICs, STM32, etc) could benefit from this, too.
• Makefile support: Right now you need to compile the library by hand, or import it into your IDE. It might be a good idea to ship along a Makefile.

[udoklein]

Hi Karol,

I get you point. However this library was developed to promote my Blinkenlighty Board (http://www.amazon.de/gp/product/3645651306/?ie=UTF8&camp=1638&creative=6742&linkCode=ur2&site-redirect=de&tag=wwwblinkenlig-21). Since the board is Arduino compatible the library will also work with "old style" Arduinos. Old refers to boards that still feature a crystal.

You are right that it has only very little Arduino dependencies. The dependencies are:

• It requires a stable 16 Mhz clock. That is a board with a 16 Mhz crystal. Actually anything that is stable and can be divided to 1kHz will do. It also requires sufficient computational power. I doubt that it can run with less than 8 MHz.
• It uses Atmega 328 specific timer settings. Of course this might be ported easily.
• It uses Arduino's print statements for debug purposes. This could be removed.

With regard to the documentation: the library is documented in my blog: http://blog.blinkenlight.net/experiments/dcf77/dcf77-library/

This is why it refers to as an Arduino library. Because the target group are Arduino users. This is also the reason why I did not split it up into files.

You are right that doxygen + build file (I would prefer scons over make) would make the library accessible to other (none Arduino) projects. Splitting it up into several files is also something that a lot of developers may prefer.

But there is one big question here: why should I do this? As I said the library exists to promote my blog. It is also under development to satisfy my own curiosity. Making it universally usable would of course promote the library but I have some concerns with regard to my blog. It also would satisfy my curiosity at all. Or with other words: I suspect that this would cost me a lot of time without getting something out of it.

So why should I do it? If you want to push it in this direction I would happily accept contributions in the form of code cleanup and/or documentation and/or ports to other platforms. I would cover this in my blog of course.

Please do not get me wrong. I did not stop working on this library. It is just that I rather prefer to add more noise resilence than to port it to more platforms or to document it outside of my blog. If you or someone else wants this I will help with advice and/or answer questions on details.

Best regards, Udo

[kbabioch]

Hi,

Am 26.08.2014 um 20:15 schrieb Udo Klein:

This is why it refers to as an Arduino library. Because the target group are Arduino users.

Personally I don't see why you would like to restrain yourself to the Arduino platform and its users. I think that there are a lot of other groups of people that would vastly benefit from such a library.

But there is one big question here: why should I do this?

Because your library and your approach are unique and making it available to more people should always be a goal of an open source developer?

Making it universally usable would of course promote the library but I have some concerns with regard to my blog.

I don't get this point at all. Don't get me wrong: I totally appreciate your work and like your approach. The documentation of your efforts on your blog is great. However, most people are probably interested in a reliable and usable library and don't want to spent their time reading your blog and implementing all of it for themselves.

Quite to the contrary: Most of the people are not even capable of reproducing your results and hence resort to your library. Putting a reference to your blog into the source should be enough to get the attention of interested people.

I suspect that this would cost me a lot of time without getting something out of it.

Without a doubt one could easily spend/waste a lot of time implementing all of the things suggested above. Personally I think it would be worth the while in the end, but after all they were just suggestions. If you don't like the ideas, or want to spent your time on something else, I won't complain ;). Maybe I will give it a shot at some point in the future.

Nevertheless, thanks for your reply and happy hacking :).

Best regards, Karol Babioch