User Tag List

First 12345 Last

Results 21 to 30 of 57

  1. #21

    Default

    It's always better when we finally understand each other (and we're writing in english, kindof).

    I am much closer to agreeing with you now.

    Quote Originally Posted by alexkreuz View Post
    I think you are misunderstanding the point completely. I'll simply say .. Documentation isn't supposed to explain what the code does .. Documentation is supposed to explain the reasons why the programmer wrote what he did, when he did, and why he did .. Documentation should NEVER explain HOW he did, because the CODE is supposed to explain that part ..
    I agree with that statement, mostly. "How" comments should be local to the code doing it (not outside the function or class), and only be used when the "how" is complicated or ambiguous in the code (in which case you may want to reconsider re-writing the code, also).

    Quote Originally Posted by alexkreuz View Post
    /*Add 3 to x*/ is a perfect example of bad documentation because it described exactly what the code does .. We both agree that anybody who is a programmer should be able to read the code, and figure that part out.

    Documentation is supposed to explain to the next person reading the code, WHY the previous programmer did what he did .. "If all the attributes of the child node check out, then the child node hasn't changed"
    Maybe I just needed more context. I undertand that part of the comment, now to be some form of invariant, not simply what the code is doing--A big difference in interpretation.

    The Invariant, Pre-Condition, Post-Condition paradigm is incredibly powerful, and a standard they used to teach everyone. I'm not sure when they stopped. A Discipline of Programming

    Quote Originally Posted by alexkreuz View Post
    You know I won't get into people of different languages, because I did work on a project which was 100% commented in Japanese, but needless to say it didn't help that the "self-explanatory" variable names and such were also in Japanese. Yes it took a LOT of time reverse-engineering it and in those sort of cases its unavoidable. But that example is a worst case scenario in which case it really makes no difference whether or not you document at all.
    But if you had a Japanese-English dictonary and could translate the words, Pre-Condition, Post-Condition, and Invariant, I'd bet you would have been helped out a lot. Since you could look for those standard markers, if the comments were done that way.

    Quote Originally Posted by alexkreuz View Post
    I never suggested that documentation is an alternative for proper coding .. However I'm not going to expect the next person who touches my code to expect to read my mind .. I don't document the programming language (C# in this case) .. I document my logic .. Why I wrote what I did ..
    They are expected not to read your mind, but read the problem to be solved. I am fairly confident I could go back to code I wrote 9 years ago, refresh my memory of the problem to be solved, and understand what I was doing. The same is true when I read the code of other experience programmers (who also followed the "Discipline"). Again, the pre-condition, post-condition, invariant paradigm allows a programmer to map the problem to be solved (which usually forces invariants across the whole system) to the particular software artifacts you created (which individually will have invariants, if functioning properly).

    Quote Originally Posted by alexkreuz View Post
    I think expecting to be "verbally taught" by a former developer of the project is quite naive, since the case is more often than not that the former developer has quit the project. It tends to flow that way.
    But that doesn't keep you from "verbally teaching" others about your code.

    Quote Originally Posted by alexkreuz View Post
    My audience is composed of fellow or future programmers, and myself, who are incapable of reading my mind and figuring out the logic I used to write the code by simple telepathy, or in my case, am subject gaps in my own memory due to not caring enough about a project to remember why I wrote what I did ..
    Again, not mind reading, but problem reading. Experienced programmers use similar Design Patterns to solve similar problems over and over again. These can be fairly easily recognized if implemented in the clasical design patterns in an OO sytem. Design patterns have been around for longer than that term had been coined. There are slight variations, but there is a good reason that design memory is one of the few skills needed by all engineering disciplines. Learn to recognize and use the standard design patterns (at various levels) and you will make your work-life, and the work-lives of those that come after you much easier.

    Quote Originally Posted by alexkreuz View Post
    What can I say .. I'm expected to program in the real world whether i like it or not .. And in the real world documentation is required to be in english since more often than not, the paycheck comes from somebody who signs it in english.
    Don't use "I work in the real world" as an excuse not to make that world a better place. More documentation does not equal better documentation. Reference the design patterns you used, the invariants of your system, the pre-conditions and post-contitions where appropriate in your "English" documentation. This is not "nerd" speak. These are common words and idioms used by practicing software engineers and programmers, and is handy in whatever language(natural and programming) you are required to use.

    Quote Originally Posted by alexkreuz View Post
    By the way, I did google this subject since I was curious what the thought on this topic was and needless to say its a hot debate that isn't solved elsewhere ..

    Linux.com :: How to document your code

    However thanks to our discussion and my following "research" I found an amazing documenting resource called Doxygen which automatically generates external HTML documentation for your code. It will give summaries and such as well provided they were documented in the first place in the code. I think you should check it out cuz I found it pretty amazing.

    Doxygen
    I knew about Doxygen. Just following their format is better than "plain english". Because, then I can strip your comments if I find out they are not of much use.

    Accept the past. Live for the present. Look forward to the future.
    Robot Fusion
    "As our island of knowledge grows, so does the shore of our ignorance." John Wheeler
    "[A] scientist looking at nonscientific problems is just as dumb as the next guy." Richard Feynman
    "[P]etabytes of [] data is not the same thing as understanding emergent mechanisms and structures." Jim Crutchfield

  2. #22
    filling some space UnitOfPopulation's Avatar
    Join Date
    Sep 2007
    MBTI
    ENTJ
    Posts
    3,272

    Default

    I have programmed since about 5 or 6 years old.

    Your programmer personality type is: DHSC

    You're a Doer.
    You are very quick at getting tasks done. You believe the outcome is the most important part of a task and the faster you can reach that outcome the better. After all, time is money.

    You like coding at a High level.
    The world is made up of objects and components, you should create your programs in the same way.

    You work best in a Solo situation.
    The best way to program is by yourself. There's no communication problems, you know every part of the code allowing you to write the best programs possible.

    You are a Conservative programmer.
    The less code you write, the less chance there is of it containing a bug. You write short and to the point code that gets the job done efficiently.


    I was absolutely shocked at seeing the last code example with comments more than code. I am trying to get over it.

  3. #23
    The Unwieldy Clawed One Falcarius's Avatar
    Join Date
    Apr 2007
    MBTI
    COOL
    Enneagram
    5w4
    Socionics
    Dino None
    Posts
    2,565

    Default

    DHSB
    Quote Originally Posted by Thalassa View Post
    Oh our 3rd person reference to ourselves denotes nothing more than we realize we are epic characters on the forum.

    Narcissism, plain and simple.

  4. #24
    Senior Member Bushranger's Avatar
    Join Date
    Apr 2007
    MBTI
    INTP
    Posts
    169

    Default

    Quote Originally Posted by Santtu View Post
    I was absolutely shocked at seeing the last code example with comments more than code. I am trying to get over it.
    What was silly was defining a function to perform standard addition.



    ygolo:

    Liberal coding technique is not only about the comments, but also how you space the code, how you group statements together, how you name identifiers and how you make conventions (e.g. design patterns) recognizable.

    With modern programmer's editors, long variable and class names do not cost any extra effort, storage space is cheap, programmer time is not.

    The best place to be is somewhere between the test's concept of liberal and conservative. Be concise and well structured, make use of common idioms of the language you are using. Be Pragmatic, bit twiddling requires a different approach than application development.
    I'll get you my pretty, and your little hermit crab too!

  5. #25
    filling some space UnitOfPopulation's Avatar
    Join Date
    Sep 2007
    MBTI
    ENTJ
    Posts
    3,272

    Default

    On documentation: I also try to think my "target audience" and place the code so as to facilitate easy reading. I dont always have the time to properly align every space and tab, especially if I write something with notepad and not with an auto-intendating editor.

    I find it required to explain advanced mathematics if I sometimes use such in an unexpected place.

  6. #26
    Senior Member Bushranger's Avatar
    Join Date
    Apr 2007
    MBTI
    INTP
    Posts
    169

    Default

    Quote Originally Posted by ygolo View Post
    Society as a whole is not where it could be with the aid of computers.
    The computer tech. (software and hardware) is not where it could be.
    Programmer productivity is not where it could be.
    The productivity of you average office worker is not where it could be.
    In 20-30 years they will look back at how we used computers and wonder how we ever confused it with productivity.

    The best thing that has happened so far in this regard is the introduction of the modern mobile phone. It is not that they are great examples of information technology (the software in particular, stinks), but that they are starting to make people understand that a computer can be more than a box that sits on their desk.
    I'll get you my pretty, and your little hermit crab too!

  7. #27
    Senior Member Bushranger's Avatar
    Join Date
    Apr 2007
    MBTI
    INTP
    Posts
    169

    Default

    Quote Originally Posted by Santtu View Post
    especially if I write something with notepad and not with an auto-intendating editor.
    My sympathies.
    I'll get you my pretty, and your little hermit crab too!

  8. #28

    Default

    Quote Originally Posted by Bushranger View Post
    What was silly was defining a function to perform standard addition.



    ygolo:

    Liberal coding technique is not only about the comments, but also how you space the code, how you group statements together, how you name identifiers and how you make conventions (e.g. design patterns) recognizable.

    With modern programmer's editors, long variable and class names do not cost any extra effort, storage space is cheap, programmer time is not.

    The best place to be is somewhere between the test's concept of liberal and conservative. Be concise and well structured, make use of common idioms of the language you are using. Be Pragmatic, bit twiddling requires a different approach than application development.
    Regarding whitespace -- Tabs are evil. Not a big deal in general since I had scripts that reformatted the way I liked or the way coding convention dictated.

    Regarding variable names--descriptive, but as concise as possible, and or follows pre-supposed project wide coding standards. Single letters for some loop indexes are fine (unless you are looping over some iterator of special significance). For classic, Floyd's algorithm, for example, i,j, and k are perfectly acceptable. For other math-related algorithms, using conventional, usually single letter variables is also OK.

    I wrote programs so that they could be easily read and modified easily. That usually means as short as possible. I made exceptions only when clarity dictated I write longer code, or add extra comments. Peer-review is excellent feedback on what is appropriate (experienced reviewers I knew showed preference for shorter).

    Accept the past. Live for the present. Look forward to the future.
    Robot Fusion
    "As our island of knowledge grows, so does the shore of our ignorance." John Wheeler
    "[A] scientist looking at nonscientific problems is just as dumb as the next guy." Richard Feynman
    "[P]etabytes of [] data is not the same thing as understanding emergent mechanisms and structures." Jim Crutchfield

  9. #29

    Default

    Quote Originally Posted by Bushranger View Post
    In 20-30 years they will look back at how we used computers and wonder how we ever confused it with productivity.

    The best thing that has happened so far in this regard is the introduction of the modern mobile phone. It is not that they are great examples of information technology (the software in particular, stinks), but that they are starting to make people understand that a computer can be more than a box that sits on their desk.
    Says the man who wants to use an abacus, wants to do all scientific modeling by hand, wants to run expensive real-life experiments whenever possible, will pick his brokerage firm to be the one who enters his trades by hand and goes purely by opinion, wants to fly in only klunky, noisy old planes, drive only cars without curves, wants no part in the knowledge gained in the human-genome project, wants his flight luggage handled like in a third world country, Wants to go back to the old days of standing in line at every gov't office, wants all his financial information in paper form, ......

    No, computing isn't about productivity, No. :rolli:

    Accept the past. Live for the present. Look forward to the future.
    Robot Fusion
    "As our island of knowledge grows, so does the shore of our ignorance." John Wheeler
    "[A] scientist looking at nonscientific problems is just as dumb as the next guy." Richard Feynman
    "[P]etabytes of [] data is not the same thing as understanding emergent mechanisms and structures." Jim Crutchfield

  10. #30
    Junior Member Hoth's Avatar
    Join Date
    Jun 2007
    MBTI
    ISTP
    Posts
    9

    Default

    Doer, high level, solo, conservative.

    Quote Originally Posted by ygolo View Post
    I saw this once:
    /*hack put in to fix issues*/
    That's a comment I've written many times. Sometimes a quick fix is necessary, and it's best to keep track of where so it can be improved later. Doing a major rewrite creates bugs which you may not want to introduce to a stable release, the hack is safer.

    My comments are only notes to myself though, being self-employed. The inability of others to understand it just works as intellectual property protection.

Similar Threads

  1. Jung Preference Exploration Personality Test (Similarminds)
    By MerkW in forum Online Personality Tests
    Replies: 140
    Last Post: 06-27-2014, 06:25 AM
  2. Philosophical personality test
    By SolitaryWalker in forum Online Personality Tests
    Replies: 323
    Last Post: 09-03-2013, 10:06 PM
  3. Magical Personality Test
    By surgery in forum Online Personality Tests
    Replies: 124
    Last Post: 07-14-2009, 10:49 AM
  4. The brutally honest personality test
    By Sahara in forum The Bonfire
    Replies: 64
    Last Post: 02-28-2009, 02:06 PM
  5. The Egoload Personality Test
    By UnitOfPopulation in forum Online Personality Tests
    Replies: 5
    Last Post: 12-16-2007, 04:46 AM

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
Single Sign On provided by vBSSO