3

write comment above block of code

or pull block of code out into method and work the comment into method name

Comments
  • 4
    The latter. Always.
  • 1
    Usually the latter but it depents on how many lines of code.
  • 3
    I don't write comment blocks often - but when i do, they contain URLs and explanations which don't make good function names.

    You can do both: Pull out the code in its own function and comment it.
  • 2
    public void weNeedToDoThisAsAWorkaroundForTheThirdPartyServicesRetardedImplementationOfOAuth(Credentials creds) {...}

    Yep, this works for me, thanks for the tip
  • 1
    Always avoid comments by either extracting code into methods with descriptive names or storing intermediate results in variables with descriptive names.
  • 1
    @Lensflare yes, but then also write comments.
  • 0
    I've been working in the jenkinsfile lately with groovy. I'm not a Java dev. I've found it helpful to have a bunch of small, well named functions, and a bunch of comments. Especially when I'm connecting to the local shell and passing bash commands
  • 2
    @Hazarth
    weNeedToDoThis -- why write that? You are calling this method, so you obviously need this
    asAWorkaround -- it's okay, but could be compacted without losing meaning: 'workaround'. Although I'd skip that part completely
    forTheThirdPartyServices -- too many unnecessary words that do not add any value. Name the party, as the w/around is speciffic to it. 'fb'
    implementationOfOauth -- might come as a surprise to you, but we are always dealing with implementations.. Why mention that explicitly? 'oauth' should be enough

    fbOauth() or fbOauthHack() should be enough. Concise, provides the same info as yours [and more as it mentions the 3rd party] and as a bonus - short. If you have to explain WHY [not WHAT] you need the hack - jot it down in the javadocs, esp when it's a public method
  • 0
    @neriald no. Not if they don’t add any value.
  • 1
    @netikras I mean I was joking, I only used "ThirdParty" because I wasn't currently angry at any of them, didn't wanna throw shade :D
  • 1
    @Hazarth I know :) Still wanted to mess around with your comment :p
Add Comment