We need to make source code more english so non-engineers will understand it



  • Recently our practices changed sharply, with no real change in management, from "We don't care as long as it works" to weekly code reviews and meetings to ensure the software design document for that project is being followed correctly. That lasted about 3 weeks. Now they want the code review to be easier to manage, so they are asking for comment blocks on each part of code stating exactly why that piece of code was written, the purpose of it, and the relevent point of the software design document that it complies to. 

    The end point of this is to "Make the source code more english for non-engineers to review". 

    So it doesn't matter if the code actually does what you say it does (as it'll be reviewed by non-engineers), as long as you have a comment block for each part of the design spec (and no more, otherwise they'll probably get confused and reject it) so they (assumingly) can tick off each point in the documentation. 

     



  • Isn't that how COBOL came to be?



  • @da Doctah said:

    Isn't that how COBOL came to be?

    Pretty much.  Well, if you want to get technical, COBOL was forged by demons from the souls of aborted fetuses in the fires of Hell to be used as a weapon against the forces of Heaven in the battle at the end of days.  But other than that?  Same thing.


  •  To bad there's no one they can hire to help in translating design specs into code and then independently verifying that the code meets the specs, so non-engineers wouldn't have to be burdened like this.



  • @Mole said:

    Recently our practices changed sharply, with no real change in management, from "We don't care as long as it works" to weekly code reviews and meetings to ensure the software design document for that project is being followed correctly. That lasted about 3 weeks. Now they want the code review to be easier to manage, so they are asking for comment blocks on each part of code stating exactly why that piece of code was written, the purpose of it, and the relevent point of the software design document that it complies to.

    I will admit that the above does seem to be a bit strict, but apart from that it's basically best practice.

    @Mole said:

    The end point of this is to "Make the source code more english for non-engineers to review".

    I've yet to meet any non-programmer who's eyes will not glaze over when confronted with non-MS-word documents that might contain code. What you describe might be possible with flunkt out CS/IT students, but not with run of the mill humans.


  • @stratos said:

    @Mole said:

    Recently our practices changed sharply, with no real change in management, from "We don't care as long as it works" to weekly code reviews and meetings to ensure the software design document for that project is being followed correctly. That lasted about 3 weeks. Now they want the code review to be easier to manage, so they are asking for comment blocks on each part of code stating exactly why that piece of code was written, the purpose of it, and the relevent point of the software design document that it complies to.

    I will admit that the above does seem to be a bit strict, but apart from that it's basically best practice.

    @Mole said:

    The end point of this is to "Make the source code more english for non-engineers to review".

    I've yet to meet any non-programmer who's eyes will not glaze over when confronted with non-MS-word documents that might contain code. What you describe might be possible with flunkt out CS/IT students, but not with run of the mill humans.

     

    If I'm understanding Mole correctly, the WTF is that they have implemented a "code review" that doesn't actually review the code, but only verifies that the comments in the code match the expectations. 



  •  Bingo. The WTF is that reviewing comments is not a "code review".



  • @DeepThought said:

    If I'm understanding Mole correctly, the WTF is that they have implemented a "code review" that doesn't actually review the code, but only verifies that the comments in the code match the expectations. 
     

     

    Christ, DeepThought, you really need to keep up.  They are attempting to open the gates of hell (again) so they can outsource to demons who will forge, in the fires of hell, a new language from the souls of aborted fetuses to be used as a weapon against the forces of Heaven in the battle at the end of days.

     

    Can you PLEASE follow along?



  •  @aesis said:

    @DeepThought said:

    If I'm understanding Mole correctly, the WTF is that they have implemented a "code review" that doesn't actually review the code, but only verifies that the comments in the code match the expectations. 
     

     

    Christ, DeepThought, you really need to keep up.  They are attempting to open the gates of hell (again) so they can outsource to demons who will forge, in the fires of hell, a new language from the souls of aborted fetuses to be used as a weapon against the forces of Heaven in the battle at the end of days.

     

    Can you PLEASE follow along?



    Oops, my bad. I'll try better next time!


  • Just prefix every line in the software design document with //

    Done.



  •  I really love it when highly detailed design documents are treated as god-given commands that must be tenaciously followed into the least detail. You see, when we programmers write, say, 10000 lines of code, there will be several bugs in it (maybe 100 or so). But those analysts and designers, they write 200 pages of technical specifications, at nearly the same level of detail like source code, without the ability to use tests, debuggers etc., and still there is not a single error in the whole document. They must be real geniuses.



  • @ammoQ said:

     I really love it when highly detailed design documents are treated as god-given commands that must be tenaciously followed into the least detail. You see, when we programmers write, say, 10000 lines of code, there will be several bugs in it (maybe 100 or so). But those analysts and designers, they write 200 pages of technical specifications, at nearly the same level of detail like source code, without the ability to use tests, debuggers etc., and still there is not a single error in the whole document. They must be real geniuses.

     

    It's because spelling and grammar mistakes don't segfault the reader of said document, the syntax is horribly complex though. 



  • @ammoQ said:

     I really love it when highly detailed design documents are treated as god-given commands that must be tenaciously followed into the least detail. You see, when we programmers write, say, 10000 lines of code, there will be several bugs in it (maybe 100 or so). But those analysts and designers, they write 200 pages of technical specifications, at nearly the same level of detail like source code, without the ability to use tests, debuggers etc., and still there is not a single error in the whole document. They must be real geniuses.
    I'm reminded of an old post on here that links to "Special programming methodologies" and one of them is "That's in Phase 2" where important and relevant functionality is left out because it's not in the requirements doc/design doc.



  • The real WTF is that the ALM system should automatically be associating every change in the code to one and only one task, which is tied back to the corresponding requirement, which is tied back to the design document. The the weekly code review can look at just the DELTAS to the code for each task that has been worked on, and the team review (includes non-engineers) can just review the automatically created logs.



  • IMO, your management is preparing to off-shore your job.
    They want more comments not for their own elucidation, but to make it easier for cheap & low-skill developers to understand your code.

    Why do I think this?
    Without any recent high-profile code delivery failures (none that you mentioned, anyway), or push by outside business-continuity consultants, it's the next-likely explanation.



  • @aesis said:

    ...a new language from the souls of aborted fetuses to be used as a weapon against the forces of Heaven in the battle at the end of days.

     

     

    I thought that was what MUMPS was?



  • @havokk said:

    @aesis said:

    ...a new language from the souls of aborted fetuses to be used as a weapon against the forces of Heaven in the battle at the end of days.

     

     

    I thought that was what MUMPS was?

     

    The ultimate weapon from Hell:

    k ^GOD



  • @morbiuswilters said:

    To bad there's no one they can hire to help in translating design specs into code and then independently verifying that the code meets the specs, so non-engineers wouldn't have to be burdened like this.
     

    hey, wait! isn't that called "a programmer"?



  • @SEMI-HYBRID code said:

    @morbiuswilters said:

    To bad there's no one they can hire to help in translating design specs into code and then independently verifying that the code meets the specs, so non-engineers wouldn't have to be burdened like this.
     

    hey, wait! isn't that called "a programmer"?

    woosh



  • @Flatline said:

    @SEMI-HYBRID code said:
    @morbiuswilters said:
    To bad there's no one they can hire to help in translating design specs into code and then independently verifying that the code meets the specs, so non-engineers wouldn't have to be burdened like this.
     hey, wait! isn't that called "a programmer"?

    woosh

    Don't woosh around me, it's giving me a headache.



  • @Flatline said:

    @SEMI-HYBRID code said:

    @morbiuswilters said:

    To bad there's no one they can hire to help in translating design specs into code and then independently verifying that the code meets the specs, so non-engineers wouldn't have to be burdened like this.
     

    hey, wait! isn't that called "a programmer"?

    woosh

    whoosh!



  •  WHOOOOOOOOOOOOOOOOOOOOOOSH!



  •  @stratos said:

    I've yet to meet any non-programmer who's eyes will not glaze over when confronted with non-MS-word documents that might contain code. What you describe might be possible with flunkt out CS/IT students, but not with run of the mill humans.
    Seems to be true, I guess. But there's another way : some people think that code should tend to become closer and closer to "natural speech". There's this Windev thing (must have said "pile of rotting gargbage" but I so want to be neutral about this fucking mess) aiming for that very purpose. They say it's 10 times faster to create an application, partially because of the "easiness" of its syntax.

    Just an example of how you can declare strings (this exact syntax is valid and encouraged by PCSoft (this langage makers/sellers) :

    MyString1 and MyString2 are strings.



  • @toshir0 said:

    There's this Windev thing (must have said "pile of rotting gargbage" but I so want to be neutral about this fucking mess) aiming for that very purpose.
     

     What.  The.  FUCK.  Pity the poor bastard forced to use this.  Mock the one who chooses to.

     Edit:  It even uses IF..THEN..END. Bonus WTFery for emulating VB.



  • @toshir0 said:

    .... There's this Windev ....

    I just paged through the Windev 14 brochure. I wasn't sure if the product was a programming environment or an automated porn generator, given the pics that were on each page. Especially when you see the pics on page 57 that highlight the "Domotics" section. And I am totally confused as to what the pic on page 70 was meant to be illustrating.


  • Discourse touched me in a no-no place

    @toshir0 said:

    some people think that code should tend to become closer and closer to "natural
    speech".
    Isn't that what 4GL (at least in the 70's/80's/90's) was supposed to fix? Then 5GL came along to point out the inadequacies?



    It all boils down to (I hope) the people critiquing software must be, at least, able to (re)write the software (under the same constraints) they're critiquing. Which isn't really apparent in the first post.



  • @toshir0 said:

    But there's another way : some people think that code should tend to become closer and closer to "natural speech".

    Those people need to read No Silver Bullet.

    Until natural language is so verbose, specific, accurate and makes absolutely no assumptions-- well, then you could code with it. Maybe. Lawyers are getting pretty close.

    But until then, there's no easy way to turn requirements into code.



  • @Smitty said:

    What.  The.  FUCK.  Pity the poor bastard forced to use this.  Mock the one who chooses to.
    I've been this poor bastard. (for three months only thanks, it was a short mission)

    To be more precise, It was slighty worse than working directly with Windev : I had to develop sort of an extranet with Webdev, the web add-on associated with it. No visibility at all on the generated code, an IDE made to turn the most sane being into a slaughtering machine, and so on. And of course, the website I was asked to develop would have to interact with the "main application". It was a giant, multi-headed monster, developped with an outdated version of Windev, developped by only one man, ingeneer but not in IT (aeronautics, WTF ?!), at home, with nearly no technical contact with anyone, making himself the specifications as he coded(1). Could it be worse ? Yes, of course. Long before I heard of it, the initial time estimate (I'm not sure this is correct for the date a project must be done and working, sorry for my poor english) was 6 months of development. When I took that mission, that first time estimate was more than two years passed, and the software didn't have the tiniest shitty feature working without random bugs. If I can find it in old saves, I'll post here the database "schema" : a painful memory...

    (1) a marvelous feature of Windev : post-generating the UML analysis of your project ! Isn't it wonderful ? You can just code like hell, and when your shitty software is done, you click on a few "next" boxes to get very colorful and entreprisey-looking graphs to prove you're a true ingeneer with conception and architecture skills. Sexy, huh ? *vomits with eyes open*



  • @toshir0 said:

    I've been this poor bastard.
     

    ...wait... so it's not a spoof? A joke? A prank? I've paged through that brochure a bit, and so far, there's nothing there. It's the English equivalent of Lorem Ipsum.

    There's no such beast.

    You're pulling our dicks legs.



  • I'm still waiting for the language that has IF...THEN...OTHERWISE. There are languages which are close (SQLs SELECT) but I've not seen an IF statement like that yet. 

    But, regardless of how "like spoken speech" a language becomes, the actual code writing is only 5% of a project. The other 95% is always going to be the documentation - If you can't describe how the software will implement each specified requirement, the language doesn't matter. 

    [Everytime we have a "We need more engineers!" drive we are flooded with people that "Know everything there is to know about C", but they fail at the logic solving part before evening writing a single line of code]



  • Actually an "Unless .... Do ....." would make certain operations syntactically cleaner....



  • @dhromed said:

    @toshir0 said:

    I've been this poor bastard.
     

    ...wait... so it's not a spoof? A joke? A prank? I've paged through that brochure a bit, and so far, there's nothing there. It's the English equivalent of Lorem Ipsum.

    There's no such beast.

    You're pulling our dicks legs.

    Well, it's got a girl with boobs there.


  • @TheCPUWizard said:

    Actually an "Unless .... Do ....." would make certain operations syntactically cleaner....

    Perl and Ruby both have this.



  • @toshir0 said:

    Seems to be true, I guess. But there's another way : some people think that code should tend to become closer and closer to "natural speech".

    I think that natural speech shouuld tend to become closer to code, in terms of clearness, compactness, and unambiguity.



  • @Abdiel said:

    I think that natural speech shouuld tend to become closer to code, in terms of clearness, compactness, and unambiguity.

    We had people on my degree course who talked like that but fortunately they stuck together and could be easily avoided by going to the pub.



  •  Well we at least know what happens when some linguist tries to make a programming language. You end up with Perl.



  • @stratos said:

     Well we at least know what happens when some linguist tries to make a programming language. You end up with Perl.

    Perl!?  Designed by a linguist?

    I thought the design of Perl came about because it was back in the bad old days when everyone connected to the Internet by dial-up modem, and just as Larry Wall was preparing to post the language spec to Usenet, he got a really bad burst of line noise.




  • @DaveK said:

    Perl!?
     

    Yea.



  • AFAIK, larry wall and his wife are both linguists and they wanted to go to africa to document some weird language. But either he or his wife got sick so he created perl instead.



  • @stratos said:

    AFAIK, larry wall and his wife are both linguists and they wanted to go to africa to document some weird language. But either he or his wife got sick so he created perl instead.

    That must have been mental rather than physical illness, yeah?  Because most perl code does read exactly like schizophasic word salad...



  • @DaveK said:

    @stratos said:

    AFAIK, larry wall and his wife are both linguists and they wanted to go to africa to document some weird language. But either he or his wife got sick so he created perl instead.

    That must have been mental rather than physical illness, yeah?  Because most perl code does read exactly like schizophasic word salad...

    I imagine that Perl could be considered the salmiakk of programming languages.

    Certainly once you do understand its heavy use of symbols, there is no way back. It's true that it was created with linguistic principles, but I see no evidence of that in the finished product.



  • 2000 years from now, they're going to find an old, crusty iPad; engineer away to power it, use it*, and discover an obfuscated section of Perl.

    It will be catalogued next to Linear A, another yet undeciphered language.

     

     

    *) because that shit is intuitive, yo.



  • @Daniel Beardsmore said:

    It's true that it was created with linguistic principles, but I see no evidence of that in the finished product.

    Don't be silly, it's full of them, the implicit variables, the shorthands that litter the language. It is just for that reason that perl syntax can become needlessly complex, just like with most natural languages.


Log in to reply