Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.programming > #6983 > unrolled thread

First Major Software Development Project

Back to article view | Back to comp.programming

Contents

  First Major Software Development Project Taylor Street <taylorkstreet@outlook.com> - 2016-10-21 23:52 -0700
    Re: First Major Software Development Project Julio Di Egidio <julio@diegidio.name> - 2016-10-22 06:22 -0700
    Re: First Major Software Development Project "J. Clarke" <j.clarke.873638@gmail.com> - 2016-10-22 15:57 -0400
    Re: First Major Software Development Project David Brown <david.brown@hesbynett.no> - 2016-10-24 16:25 +0200

#6983 — First Major Software Development Project

So, I am a new electrical engineer, but I just got put on a software 
development project.  It is a development board with a bunch of sensor 
attachments.  The code for the board has mostly been written and a lot 
of the driver libraries for the sensor attachments have been written.  I 
have to write a few more libraries for some new sensors.

I don't have a problem with C++.  I am very familiar with it.  However, 
I have never been taken on a massive development project before.  What's 
more is that the other programmer doesn't document his 
code...whatsoever.  The development software has automatic documentation 
through a markdown language, but he doesn't use it.  Nor does he even 
comment his code, other than the occasional line that was 
self-explanatory (e.g. "// end of for loop").

My first question is, do you have any tip for someone who is on their 
first software development project?  Secondly, how should I go about 
figuring out this code?  Should I write documentation for it?  Should I 
try to construct UML diagrams?  Flowcharts?  Stick figures? 
Role-playing?  ESP?

Any help or thoughts would be appreciated...even unhelpful, sarcastic, 
funny ones.

[toc] | [next] | [standalone]

#6984

On Saturday, October 22, 2016 at 8:52:32 AM UTC+2, Taylor Street wrote:

> So, I am a new electrical engineer, but I just got put on a software 
> development project.  It is a development board with a bunch of sensor 
> attachments.  The code for the board has mostly been written and a lot 
> of the driver libraries for the sensor attachments have been written.  I 
> have to write a few more libraries for some new sensors.

That sounds pretty cool.

> I don't have a problem with C++.  I am very familiar with it.  However, 
> I have never been taken on a massive development project before.  What's 
> more is that the other programmer doesn't document his 
> code...whatsoever.  The development software has automatic documentation 
> through a markdown language, but he doesn't use it.  Nor does he even 
> comment his code, other than the occasional line that was 
> self-explanatory (e.g. "// end of for loop").

An expert programmer would not document very much, namely, nothing that
is already clear enough... e.g. certainly not language idioms or common
programming patterns.  OTOH, an expert programmer would certainly use
meaningful names and structures, unless obscuring the code was a requirement.

Also, as you speak in the present tense, another critical question is:
does he answer questions if you ask?  (No need to tell us.)

> My first question is, do you have any tip for someone who is on their 
> first software development project?

Yes, Murphy's Law: don't panic.

> Secondly, how should I go about 
> figuring out this code?

It's called reverse-engineering.

> Should I write documentation for it?  Should I 
> try to construct UML diagrams?  Flowcharts?  Stick figures? 
> Role-playing?  ESP?

Don't bother about formalities, despite widespread myths informal drawing,
even just paper and pen, is just fine.  Things can get more formal when they
need to get more formal.

Also, and truly in the agile spirit, just document what you need to understand,
this piece or that, and when you need it: just nothing more than that.

There is then advice for dealing with legacy systems, but I think that's
beyond the scope here.

> Any help or thoughts would be appreciated...even unhelpful, sarcastic, 
> funny ones.

Welcome on board,

Julio

[toc] | [prev] | [next] | [standalone]

#6985

In article <nuf2bc$1egg$1@gioia.aioe.org>, taylorkstreet@outlook.com 
says...
> 
> So, I am a new electrical engineer, but I just got put on a software 
> development project.  It is a development board with a bunch of sensor 
> attachments.  The code for the board has mostly been written and a lot 
> of the driver libraries for the sensor attachments have been written.  I 
> have to write a few more libraries for some new sensors.
> 
> I don't have a problem with C++.  I am very familiar with it.  However, 
> I have never been taken on a massive development project before.  What's 
> more is that the other programmer doesn't document his 
> code...whatsoever.  The development software has automatic documentation 
> through a markdown language, but he doesn't use it.  Nor does he even 
> comment his code, other than the occasional line that was 
> self-explanatory (e.g. "// end of for loop").
> 
> My first question is, do you have any tip for someone who is on their 
> first software development project?  Secondly, how should I go about 
> figuring out this code?  Should I write documentation for it?  Should I 
> try to construct UML diagrams?  Flowcharts?  Stick figures? 
> Role-playing?  ESP?
> 
> Any help or thoughts would be appreciated...even unhelpful, sarcastic, 
> funny ones.

Knowing the programming language is only part of the battle, it's having 
knowledge of the product you are developing that is the hard part.  I 
used to think I was a pretty good programmer and for the kind of work I 
was doing I was, but I changed industries a couple of years ago and I'm 
finding it an uphill battle learning the terminology and concepts of the 
new industry. "Meaningful variable names" are only meaningful if you 
know what the words mean, and people with a lot of experience tend to 
assume that everyone else has the same background.  Code I work with 
today often has variable names like "Q" and "M" that, if you open a 
textbook in the field, are exactly the texbook terms for particular 
concepts.

I find that colored markers and colored pens help, expecially when a 
heavily nested IF statement spans several pages or gotos are involved.

If you want the next guy to think highly of you, comment it so that some 
archeologist digging it up a thousand years from now will be able to 
figure out why it exists and what it's doing.   That will help you next 
time you need to fix it too.  I admit--I don't do that--hardly anybody 
does--but it's a goal to strive for.  But even if time doesn't permit 
that level of commenting, do put explanatory notes on any pieces that 
give you trouble or where the purpose isn't obvious or where the code is 
implementing some published standard process that isn't obvious from 
context, or where every time you look at it you have to scratch your 
head for a while to remember what it does.

Use whatever diagramming method works for you.  If you're stuck on a 
huge module a flowchart can be a big help, but it's usually overkill.

Once the other guy figures out that you know what you're doing he's 
liable to open up a little bit.

If you need an answer, the other programmer might not be the guy who has 
it--learn who's who in your organization--since you're writing code to 
support hardware there might be a hardware guy somewhere who's a 
goldmine of information.  

[toc] | [prev] | [next] | [standalone]

#6986

On 22/10/16 08:52, Taylor Street wrote:
> So, I am a new electrical engineer, but I just got put on a software
> development project.  It is a development board with a bunch of sensor
> attachments.  The code for the board has mostly been written and a lot
> of the driver libraries for the sensor attachments have been written.  I
> have to write a few more libraries for some new sensors.
> 
> I don't have a problem with C++.  I am very familiar with it.  However,
> I have never been taken on a massive development project before.  What's
> more is that the other programmer doesn't document his
> code...whatsoever.  The development software has automatic documentation
> through a markdown language, but he doesn't use it.  Nor does he even
> comment his code, other than the occasional line that was
> self-explanatory (e.g. "// end of for loop").
> 
> My first question is, do you have any tip for someone who is on their
> first software development project?  Secondly, how should I go about
> figuring out this code?  Should I write documentation for it?  Should I
> try to construct UML diagrams?  Flowcharts?  Stick figures?
> Role-playing?  ESP?
> 
> Any help or thoughts would be appreciated...even unhelpful, sarcastic,
> funny ones.

If you are trying to understand existing code, I find doxygen quite a
useful tool - even if there are no doxygen comments in the code.  Just
get doxygen to "document" /everything/.  Then you get a browser
interface which is searchable, with clickable cross-references for all
your identifiers, call graphs (caller and callee), include graphs, etc.
 It can make it easier when you are trying to find out what on earth the
function "foo" does - you can easily find out what code calls it, or
where it is called from.

You can also easily find the problem parts - variables that are accessed
from lots of different modules, call graphs with complicated recursion
loops, etc.

It does not solve everything, but I find it a handy tool.

[toc] | [prev] | [standalone]

Back to top | Article view | comp.programming

csiph-web