Email: Password: Remember Me | Create Account (Free)

Back to Subject List

Old thread has been locked -- no new posts accepted in this thread
Andy Neil
03/19/10 08:44
Read: 3003 times
Basingstoke
Uk


 
#174319 - Unfortunately agree
Responding to: Oliver Sedlacek's previous message
Oliver Sedlacek said:
Of particular note I'm annoyed by ... Poor coding standards


I'm afraid I would tend to agree.

:-(

Someone made the same comment recently on the STM32 forum; this was my reply
I said:
ST (like too many others) seem to have totally missed the point and target audience of "sample" or "example" code:

* The Purpose is to inform and explain;

* The Target Audience is people who are not familiar with the software and/or the hardware.

Clearly, these are not served by terse and/or sparse comments, nor by using any kind of "clever tricks" in the source code.

Sample code needs to be exemplary in both the quantity and the quality of its comments, and those comments need to clearly describe each step of the process, and each variable used, and the project settings, etc - as well as giving an overview!

"It'd be nice if there were lots of comments to explain what is going on."

Not just "nice" - absolutely essential if it is to serve its purpose as example code!

"Then again how many people do that?"

But "most people" are not writing example code!
The specific purpose of example code requires it!


https://my.st.com...tviews=333


List of 65 messages in thread
TopicAuthorDate
Whinge about Eval and Quickstart kits      Oliver Sedlacek      03/19/10 08:10      
   Most time probably spent with other work tasks      Per Westermark      03/19/10 08:17      
   while I basically agree, some comments      Erik Malund      03/19/10 08:24      
      Missing the point (ed)      Andy Neil      03/19/10 08:34      
      What I want..      Oliver Sedlacek      03/19/10 09:32      
         What I want..      Andy Neil      03/19/10 11:48      
            It's a non-starter ... What if I need 5.9908 MHz?      Richard Erlacher      03/26/10 10:30      
               re: What if I need 5.9908 MHz?      Andy Peters      03/26/10 11:12      
                  I think Richard was being generic there...      Andy Neil      03/26/10 11:47      
      Here's what I'd want ...      Richard Erlacher      03/26/10 10:23      
   Unfortunately agree      Andy Neil      03/19/10 08:44      
      Proper documentation is part of the task      Per Westermark      03/19/10 08:54      
         pedagogical      Andy Neil      03/19/10 09:11      
         Fundamental problem with GUIs      Andy Neil      03/19/10 09:16      
            GUI Settings Documentation        Michael Karas      03/19/10 09:36      
               Screenshots      Andy Neil      03/19/10 10:31      
   only today      Jez Smith      03/19/10 10:09      
      That's the reason there's so much junk      Richard Erlacher      03/26/10 16:05      
   as the little girl pointed out...      Jan Waclawek      03/19/10 14:47      
   Previously, on 8052.com...      Andy Neil      03/19/10 16:18      
   who's evaluating who?      James Hinnant      03/20/10 21:09      
   Changing the installation location.      Christoph Franck      03/22/10 02:19      
      filenames with spaces in it      Andy Neil      03/22/10 03:28      
         Exactly      Per Westermark      03/22/10 03:33      
         Bizarre bugs.      Christoph Franck      03/22/10 04:19      
      Spaces      Per Westermark      03/22/10 03:30      
         "My Documents" directory      Andy Neil      03/22/10 03:50      
            May and may...      Per Westermark      03/22/10 05:17      
   Xilinx      Andy Peters      03/23/10 13:06      
      Or, perhaps worse, none ...      Richard Erlacher      03/26/10 16:10      
   What is the purpose?      Andy Neil      03/23/10 17:35      
      The way I see it      Jez Smith      03/24/10 00:20      
         Disagree (mostly)      Andy Neil      03/24/10 00:52      
            well      Jez Smith      03/24/10 01:01      
               quite so      Andy Neil      03/24/10 03:53      
                  Easy to get a customer to move to a competitor      Per Westermark      03/24/10 04:18      
                     The problem stems from...      Jez Smith      03/25/10 01:48      
                        Misses in communication and assumptions alas common      Per Westermark      03/25/10 03:26      
                           'first demo' to a customer ...      Erik Malund      03/25/10 05:42      
                              That's because      Jez Smith      03/25/10 10:53      
               not only that ...      Richard Erlacher      03/26/10 22:34      
         see above ...      Richard Erlacher      03/26/10 22:32      
      I've looked at a lot of "eval" boards ...      Richard Erlacher      03/26/10 22:29      
         app notes      James Hinnant      03/27/10 03:44      
            a CD with their demo boards      Andy Neil      03/27/10 03:47      
            what good would that do?      Erik Malund      03/27/10 05:31      
               mark this on your calendar ... Erik and I agree!      Richard Erlacher      03/27/10 08:39      
               project files      James Hinnant      03/30/10 13:35      
                  how?      Erik Malund      03/30/10 15:02      
                  run != tested      Andy Neil      03/30/10 16:53      
                  That's exactly the wrong attitude      Oliver Sedlacek      03/31/10 03:19      
                     wrong or not, makes sense      Erik Malund      03/31/10 06:09      
                        But      Andy Neil      03/31/10 06:31      
                        What goes around comes around      Per Westermark      03/31/10 06:57      
                           I think something got lost      Erik Malund      03/31/10 07:03      
                              Yes MANUFACTURERS      Per Westermark      03/31/10 07:22      
                                 Per, I do not disagree      Erik Malund      03/31/10 07:27      
                                    no synergy?      Jan Waclawek      03/31/10 08:00      
                                       au contraire      Erik Malund      03/31/10 08:34      
                                       the key is in UNDERSTANDING the example      Richard Erlacher      04/01/10 07:22      
                                    deviate vs derivative      Andy Peters      03/31/10 10:39      
                                       SILabs      Erik Malund      03/31/10 11:30      
                                          deviates      Andy Peters      04/02/10 12:49      
                        Portable within company portfolio      Oliver Sedlacek      03/31/10 08:01      
   Devkits      Andy Neil      03/31/10 15:53      

Back to Subject List