1. #1
    Ext JS Premium Member
    Join Date
    Feb 2009
    Posts
    440
    Vote Rating
    2
    Jangla is on a distinguished road

      0  

    Default Suggestion: code commenting

    Suggestion: code commenting


    Hi. Can I make one small request when it comes to posting tutorials and examples? Comment your code a LOT more. Even the simplest examples here have dozens of lines of code and almost no commenting. I know there's text outside the code blocks but this is invariably cluttered with unnecessary jargon and doesn't actually explain why anything is done - it just tells you that something is being done. Case in point - the BoxComponent example; nearly 100 lines of code and not one single comment.

    Sure, I can understand that people get tired of providing n00bs with spoon-fed information but the fact is that if you don't comment your code to show why you're doing something then this issue will perpetuate and no-one will learn anything; they'll just plagiarise very similar examples and change tiny elements of it to suit their needs.

    Like it or not, the internet is full of people of all sorts of abilities - everyone has to start somewhere. My ethos has always been that skill level should not be a hindrance to progression - passion to learn is key. But if there's no-one willing to show why things are done a certain way that passion can be damped or completely die and opportunities to shine are missed.

    Just my 2 cents. Rant over.

  2. #2
    jay@moduscreate.com's Avatar
    Join Date
    Mar 2007
    Location
    Frederick MD, NYC, DC
    Posts
    16,353
    Vote Rating
    77
    jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all jay@moduscreate.com is a name known to all

      0  

    Default


    Jangla,

    Thats a great suggestion. The code in Ext is well documented, but the examples are slapped together with little. I am certainly guilty of this myself.

  3. #3
    Ext User
    Join Date
    Jul 2007
    Location
    Florida
    Posts
    9,996
    Vote Rating
    5
    mjlecomte will become famous soon enough mjlecomte will become famous soon enough

      0  

    Default


    Moved your post to its own thread.

    I'm probably guilty of over commenting if you look at my examples, extensions, etc. Some may feel it distracting to wade through all the commentary, but my IDE has a feature to toggle on/off commenting so I don't perceive that to be an issue IMO.

    I also think there is a difference between "documented" and "commented". Documented would be an interpretation of what a code block does, commented would describe more finitely why different lines are present, etc.

  4. #4
    Ext User
    Join Date
    Jul 2007
    Location
    Westerville, OH
    Posts
    15
    Vote Rating
    0
    marek_xyz is on a distinguished road

      0  

    Default


    As a long time lurker in the Ext forums and examples, I can say that MJ's "overcommenting" has been useful, especially to newcomers. I would always prefer that everyone error on the side of MJ's style of examples, especially when targeted at new Ext users.

    That said, well thought out and well-designed examples are a lot of work, and I generally appreciate any contribution. The best ones always seem to rise to the top.

  5. #5
    Ext JS Premium Member
    Join Date
    Feb 2009
    Posts
    440
    Vote Rating
    2
    Jangla is on a distinguished road

      0  

    Default


    Quote Originally Posted by mjlecomte View Post
    Moved your post to its own thread.
    Any chance you can post the link so replies can go there and not dilute this one?