Leaderboard

I put together a series of articles while working on an AF 101 presentation for our local CLD summit. Check them out and let me know what you think or if you have any questions/improvements. Part 1 – The Background Part 2 – The Actor Part 3 – Launching and Communicating Part 4 – Being Productive With Actors Basic Walkthrough – Creating a Logger

My oldest software that hasn't become "vapourware" seems to be the "windows_api_1.0.llb".It was written in LabVIEW 5 in the late 1990s but think I had it internally for a couple of years before I released it. It is posted in the CR after someone asked for it and is identical to the original except it was recompiled for 2009 and later so people could actually use it. Here is the original in LabVIEW 5. I can't actually open it any more but I'm pretty sure it is identical to the CR one. windows_api_1.0.llb

.Net is in some ways better than ActiveX in the areas Shaun mentions. ActiveX is an extension of OLE and COM which have their roots in old Windows 3.x times. Back then preemptive multitasking was something reserved for high end unix workstations and PCs had to live with cooperative multitasking. So many things in Windows 3.1 and OLE and COM assumed single threading environment or at best what Microsoft called apartment threading. This last one means that an application can have multiple threads but any particular object coming from an apartment threading component always has to be invoked from the same thread. LabVIEW having started on Mac and then ported to Windows 3.1 heavily inherited those single threading issues from both OSes. It was "solved" by having a so called root loop in LabVIEW that dispatched all OS interactions such as mouse, keyboard and OS events to whatever component in LabVIEW needed them. When LabVIEW got real multithreading support in LabVIEW 5 this root loop was maintained and located in the main thread that the OS starts up when launching LabVIEW. It is also the thread in which all GUI operations are executed. Most ActiveX components never supported anything more than apartment threading as that kept development of the component more simple. LabVIEW does honor that by executing the methods and property calls for those ActiveX components from the main thread (called usually UI Thread). That can have certain implications. Out of context or remote ActiveX components are thunked by Windows through the OLE RPC layer and the according message dispatch for this OLE thunking is executed in the Windows message dispatch routine that is called by LabVIEW in its root loop. Any even slight error in the Windows OLE thunking, ActiveX component or the LabVIEW root loop in how to handle the various events properly can lead to a complete lockup of the message dispatch and with that the root loop of LabVIEW and absolutely nothing works anymore. Theoretically other threads in LabVIEW can continue to run and actually do, but without keyboard, mouse and GUI interaction an application is considered pretty dead by most users. .Net is less suspicable to such problems but not entirely free as it still inherits various technologies from COM and OLE deep down in its belly. My personal issue with both is that they involve a very complex infrastructure in addition to the LabVIEW runtime that is: 1) has to be loaded on application startup delaying the startup even more 2) while very easy to use when it works, almost impossible to understand when things go wrong 3) being a Microsoft technology has a big chance of being obsoleted or discontinued when Microsoft tries to embrace the next hype that hits the road (DDE while still present is dead, OLE/COM superseded by ActiveX, and ActiveX is highly discouraged in favor of .Net now, Silverlight has been axed already) Betting on those technologies has had a very good chance of being siderailed so far, as NI had to find out several times including with Silverlight the last time.

I don't think the criteria I am posting is different from the general consensus of the previous replies, but it might help others as it helps me to decisively determine where to draw the line... I always filter comments based on whether they answer 'what am I doing' or 'how am I doing' something and leave out the 'hows'. The level of detail is based on what questions someone else familiar with the purpose of the SW would ask (the peer review scenario) or similarly, what I will forget about a couple months after finishing it (the SW update scenario). Exceptions would be comments answering the 'why' questions that require knowledge contained in a manual the programmer may be unfamiliar with. AQ gave one example of this earlier. Another example would be including documentation about the bits in a product's register when manipulating them.

I can pile on here. One reason not to over-comment is that then it makes it harder to figure out which comments are important. Sometimes less is more. Admittedly more often code suffers from a dearth of comments than from a surplus.

In general, Darren and I add comments to our diagrams when, during a buddy session, we actually have to explain what's going on to the other. That's our standard measure for when a comment is needed. If the buddy session proceeds without the other person getting lost as we walk through, then the code and the API documentation (i.e. the Context Help) likely suffices as it is. My instinct in this case would be to put a Diagram Disable structure down and put the other version that I had tried in the Disabled frame -- then I don't have to describe what I tried, people can look at it. Now, that is only true when the other version of the code is all prims or vi.lib VIs, things that don't cause my source code to have additional dependencies when distributing it. As much as possible, I would still prefer to include the graphical "here's what I tried" and avoid a text description of it. It is both more accurate to say "I tried this" and if someone else says, "But that other way really should, by rights, be faster..." they can benchmark it themselves easily and/or spot any errors I had in my implementation. And if the compiler takes advances, it's easy to flip in the other code.Now, having said all of that, I do tend to include "proof of correctness" comments with complex algorithms, along the lines of "This loop works because earlier in this VI we already guaranteed that there are no duplicates in the array". This is especially true when I'm relying on a less-than-obvious fact of one of the upstream functions. For example, I recently wrote a VI with the comment "This works because the Controls[ ] property of a Front Panel refnum guarantees that the controls are returned in tab order." Most people analyzing my code for correctness wouldn't know that fact, even if it was properly documented (it will be in LV 2012), so it was worthy, IMHO, of a comment.

Wow, I head slapped myself silly after seeing that image, especially since that little piece of code was my modest contribution. I completely agree about OpenG showing best practice and all, I strongly disagree that this level of documentation is best practice. Looking at the original thread, the first suggested code was slightly more complex. I thought I would see if it was faster than the completely obvious method. It turns out no. Had the more complex code been faster, as it often can be, that would have been worth a comment. My usual philosophy is that well-written G is self-documenting, and adding text comments is like writing the letters of the notes on sheet music, unnecessary and redundant. A picture is worth a thousand words, this makes it seem like a picture requires a thousand words. If I were to add a comment, it would be that I benchmarked and the simple code turned out the fastest with quick descriptions of the alternative. If I see code like that, I don't question what it is doing, I usually want to know why. If I comment "slightly faster than byte array method", that could save my future self more time than "looping over characters in the input string". Again I agree with the spirit of Jim's comment, I'd simply look for a better example. I know that I am text-averse on my BD so my code is fertile ground for lessons in commenting. I'd suggest my Trim Whitespace code as needing a few more sticky notes and not this one.

For this particulary example I disagree with you. Comment is good, but all the comments in this particular example are in my opinion not needed since the code is very straight forward. When coding in C I wouldn't either comment code like "lenVariable = strlen(strVariable) // get the length of the string" In my opinion only parts of code which are not that straightforward, certain parts of a algorithm, should be documented. When all the parts of the algorithm are straightforward, as in this case, the only thing that needs to be documented is what the algorithm exactly does, which is already done in this case. Of course one could discuss about what the exact definition is of straightforward.