|
Wordle 1,011 5/6*
π¨β¬π¨β¬β¬
β¬β¬π¨π¨β¬
π¨π¨π¨β¬β¬
π©π©β¬π©π©
π©π©π©π©π©
|
|
|
|
|
Hi All,
How does your company handle documentation of code? I can see the point once it's nailed down, a couple of pages it does this helps (algorithm, inputs & outputs), however this place doesn't do Software or Electronics (they have started to!) they have this thing of process flow charts. While this is possible with some simpler rigs (mostly embedded) with Windows code the shear size of a DLL prevents a flow chart for it. So what is a better way, I have come across Jackson diagrams which I did back at college when Pascal was the thing. They seem to muddy the water... any suggestions any one?
|
|
|
|
|
glennPattonWork3 wrote: How does your company handle documentation of code?
hahahahah deep breath ... hahahahahah
Our code base is ancient; most of the base documentation was written decades ago (yes, decade)
We have word documents for each module describing what it does, business model and a description of the UI/UX and the database tables and the error messages; the word documents are in source control.
The code itself is , err, well, documented.
CI/CD = Continuous Impediment/Continuous Despair
|
|
|
|
|
Quote: Our code base is ancient; most of the base documentation was written decades ago (yes, decade)
I laugh at you calling a decade ancient. My program is 3 decades old and still actively coded (though not for too much longer). The last good documentation was written 15 years ago.
Bond
Keep all things as simple as possible, but no simpler. -said someone, somewhere
|
|
|
|
|
i said decadeS ...
Oldest comment in the code is from 1994.
CI/CD = Continuous Impediment/Continuous Despair
|
|
|
|
|
I've got...
Quote: * ommgr1.cob 11 Apr 1992, 13:41
going once, going twice. Anyone got an older date?
Bond
Keep all things as simple as possible, but no simpler. -said someone, somewhere
|
|
|
|
|
yep... since we're having a measuring contest  I go back to 1984.
You would be AMAZED at how much old code is lurking out there.
Charlie Gilley
βThey who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.β BF, 1759
Has never been more appropriate.
|
|
|
|
|
charlieg wrote: You would be AMAZED at how much old code is lurking out there.
Yeah, and everything still compile with the latest compilers. (with some minor updates).
In my previous job, we also had files from the 80s (fortran maths stuff converted to C ).
( I can't check them, obviously),
CI/CD = Continuous Impediment/Continuous Despair
|
|
|
|
|
We use Sandcastle Help File Builder to generate documentation from the XML comments in our C# code.
If you use other languages Doxygen maybe an option.
|
|
|
|
|
Useful if the comments keep up with code changes, but too often I have seen code changed and the comments left untouched, even ignored in code reviews. Result is worse than no comments at all!
|
|
|
|
|
True, it takes some discipline to update the comments which is something some developers seem to lack ...
|
|
|
|
|
We use DoxyPress[^], a ground-up rewrite of doxygen. We switched to it when we discovered doxygen couldn't handle our code base.
They use specially-marked comments in the source code to generate documentation. The comments can use Markdown for formatting. It can generate HTML, HTML Help, LaTex, etc. It's pretty capable. Out of the box it can generate documentation from unmarked code that's useful in and of itself including outlines of the source code, a class index, call and inheritance graphs and so on. It handles C# well, unlike doxygen.
We've begun documenting our current generation product using it. Our automated build process runs DoxyPress against the code, generating source documentation for each build.
Software Zen: delete this;
|
|
|
|
|
will have to look into this. I used to use a product from SciTools, but they got stupid expensive. Guess they decided the small developer market was irrelevant. I don't have a problem paying $1200 for a product. Forcing me to do it every dang year? I don't think so.
Charlie Gilley
βThey who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.β BF, 1759
Has never been more appropriate.
|
|
|
|
|
I write all my documentation from scratch using HelpSmith.
For me, it is the only way to get concise documentation for my applications...
Steve Naidamast
Sr. Software Engineer
Black Falcon Software, Inc.
blackfalconsoftware@outlook.com
|
|
|
|
|
It really comes down to an organization that wants to enforce it's will on developers to document their $$$t. The vast majority of code is butt simple, but their are times when you are writing a nuclear detonation simulation .... that sort of arcane classified stuff that should be doc'd.
Having said that, the most important part of s/w doc is the why. This is typically driven by users - we call this tribal knowledge. In my 40+ years, I have NEVER seen any management thought to this area. There are reasons the code does what it does. It's at the business or user level. Two examples:
1) 20 years ago, I started my HMI machine development efforts. We had a rule - touch screen buttons must be at least 25mm square on the screen. Why? Well, my products worked on hot melt glue applications, so most of the time the operators had gloves on. Never documented. Walks around in people's heads. 20 years later, safety no longer allows operators near the machines. So, we're off to remote touchscreens and smart phone interfaces. Not documented.
2) Working with gluing systems. Back in the early days of this one product, we had the need to do something as a maintenance operation. The first version was coded up as an on/off driven by the touchscreen. Well, the touchscreen turned it on and then for reasons I have long forgot crashed. Leaving the unit on... making a puddle of stuff on the factory floor while the people there waited for the the touchscreen to reboot. So, we changed the process as on of "keep doing that" every second from the touchscreen. Auto shutoff in the event of a touchscreen crash. documented? nope.
It's not about the code - it's the system.
Charlie Gilley
βThey who can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety.β BF, 1759
Has never been more appropriate.
|
|
|
|
|
It's mostly due to the if 'what do we do if your are hit by a bus', my answer 'what is this 'Bus' you speak of?, the acients tell tales of them!' For most of them I have stuck a circuit diagram and the flowchart of operation and where need the embedded code (C mostly, little bit of assembly) with a flowchart. I think a flow chart for the Windows code is not really do-able, I'm using a Class and a DLL I can't, don't want to get into! 
|
|
|
|
|
... how enjoyable desktop app development is.
I've spent the last couple of weekends implementing a WPF version of our web app as a POC. There is no hope in hell of this code actually going anywhere, but I can exercise various aspects of our web app.
I've got the following stuff implemented:
0) The user can use Ctrl+/Ctrl- to grow/shrink the app's font (like a web browser) for Section 508 compliance
1) Most of the forms in the app have a listview, so I'm using my AutomaticListView component ()[^]), and have derived a ne version that automatically increases column widths to keep up with the MainWindow's font size increase/decrease.
2) I'm using my Customizable WPF MessageBox[^], with changes that include extended icons, and border colors that are aligned with the icons (green=success, blue=info, etc). This kind of mimics your typical web-based message indicators.
3) The app acts like an old-school SDI app, with each form being a UserControl and the app managing display/disposal
4) The base form class provides support for app-specific function keys, as well as the ability to augment these function keys on a form-by-form basis with pre/post event handlers, as well as the ability to override the common functionality of the function key itself.
5) We have a weird date control in the web app with "peculiar" behavior, and I've been able to succesfully duplicate it in the form of a custom control. It includes a lot of fail-gracefully code, as well as a tooltip that includes error info in the event the user does something stupid. (We don't present a calendar on our date controls because the web app has to support complete keyboard-driven input.
Overall, it's been a blast working on the desktop again. I sure miss the old days... The last time I did a desktop app for a paycheck was 2015...
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
#realJSOP wrote: has to support complete keyboard-driven input
So it is still a gov't oriented project. They're the main ones that look for that "operators will be reading forms and entering data so make it such that they don't have to look at the screen much." motif.
Iβve given up trying to be calm. However, I am open to feeling slightly less agitated.
Iβm begging you for the benefit of everyone, donβt be STUPID.
|
|
|
|
|
Any data entry system should support keyboard field movement. It doesn't matter if it's a desktop or web application.
|
|
|
|
|
Should and DOES are two different things.
Iβve given up trying to be calm. However, I am open to feeling slightly less agitated.
Iβm begging you for the benefit of everyone, donβt be STUPID.
|
|
|
|
|
It's a forensic drug testing application, and the folks in the labs use barcode scanners and keyboard input. They rarely (if ever) need to use a mouse for anything other than selecting the form they want to use.
I think this app is the most complex I've ever worked on, even more so than the tax/charitable giving software I used to do...
The complexity isn't a problem - the fact that it's a web app is what I have issues with.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013
|
|
|
|
|
#realJSOP wrote: Forum:The Lounge
... how enjoyable desktop app development is.
My current ratio of desktop/web development is about 50/50 trending toward more web development. IMHO desktop is just easier/quicker for a POC for a lot of reasons...no back button, session state, richer controls are a few that come to mind.
I can't say I prefer one or the other, but for a POC or testing, it sure is quicker to design/test/debug a desktop app. I can't tell you how many minutes a day I wait for the VS IIS Express to spin up just to test a minor edit  ...enough that I got a bigger hammer (new system with more of everything) waiting in the wings.  Another weekend and I'll make the move.
"Go forth into the source" - Neal Morse
"Hope is contagious"
|
|
|
|
|
Wordle 1,010 4/6
β¬π©β¬π¨β¬
π©π©β¬β¬π©
π©π©π©β¬π©
π©π©π©π©π©
|
|
|
|
|
Wordle 1,010 4/6
π¨β¬β¬β¬β¬
β¬π©π¨β¬β¬
π©π©π©β¬π©
π©π©π©π©π©
Isn't this a proper noun?
|
|
|
|
|
It has another meaning - which I can't refer to without making it a spoiler! 
"I have no idea what I did, but I'm taking full credit for it." - ThisOldTony
"Common sense is so rare these days, it should be classified as a super power" - Random T-shirt
AntiTwitter: @DalekDave is now a follower!
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
