Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Stack Overflow for Teams

stackoverflow.com

Post reply on HN
Print view View original

141–150 of 163 posts

Re: Stack Overflow for Teams

#141

Post by [deleted] »

zamber wrote: post #112
zip1234 wrote: post #96

Earlier quoted context omitted.

Whoever thinks comments are a code smell has probably stumbled into a nest of documented code where the documentation was out of date and didn't refer to the latest code in question, causing intense confusion. Comments can certainly be helpful but there is nothing to guarantee that they will be up to date or even useful.

Indeed. Had to port a 2k perl script with gigantic comment blocks written in German. Eventually I recreated the intended functionality with ~150 lines of JS after painfully google translating everything. JIRA references would probably be lost completely by the time I worked on it.

[deleted]

Re: Stack Overflow for Teams

#142

Post by zamber »

vgy7ujm wrote: post #131
zamber wrote: post #112

Earlier quoted context omitted.

Indeed. Had to port a 2k perl script with gigantic comment blocks written in German. Eventually I recreated the intended functionality with ~150 lines of JS after painfully google translating everything. JIRA references would probably be lost completely by the time I worked on it.

So it was less than 100 lines of actual needed Perl code in that script? ;)

More around 800 of sloc. At least I haven't had to preserve bugs. There were also red herrings in the comments, leftovers as the script was tweaked to fit business requirements. Imagine blocks like this spat around randomly between code blocks...

  ###############################################################################
  #                                                                             #
  #                               DAS IST CODE                                  #
  #                                                                             #
  ###############################################################################
  #                                                                             #
  # Das macht Dinge. Ja, ich habe diesen Übersetzer eingegeben, nur um etwas    #
  # einfügen zu können. Hoffentlich ist dies nach einer doppelten Übersetzung   #
  # noch lesbar. Wenn nicht, dann fick es einfach. Nett, es geht gut zurück.    #
  #                                                                             #
  # Natürlich wurde Interpunktion und Rechtschreibung gebrochen. Es war um das  #
  # Jahr 11, als der Übersetzer nicht über die gesamte Politur der künstlichen  #
  # Intelligenz verfügte, so dass eins von acht Wörtern nicht übersetzt wurde.  #
  # Zum Glück funktionierte es sogar mit Code, obwohl es nicht zu kompliziert   #
  # war. Andererseits sind Deutsche ziemlich zurückhaltend (oder waren, als     #
  # diese besondere Monstrosität gemacht wurde), um Englisch zu lernen, so dass #
  # selbst Variablen in der Muttersprache sein mussten. Ich verließ das         #
  # Unternehmen rund 3 Monate, weil ich eine Legacy Monstrocity (es war nur ein #
  # gehacktes Addon-Skript, das von einem Plugin-System in einem                #
  # Unternehmens-CMS lief) reparierte, war nicht meine Sache.                   #
  #                                                                             #
  ###############################################################################

Re: Stack Overflow for Teams

#143

Post by htaoerth29th »

colshrapnel wrote: post #61
bluedino wrote: post #54

There's nothing like writing up an Evernote or Wiki article on some feature, process, or how/why something works... and then nobody on the team ever reading. I love writing documentation from time to time. But this helps by getting you to write documentation for only things people are asking about.

SO is bad with search, entirely giving it away for Google to find relevant answers. In a wiki, at least I can follow the structure to find relevant pages, but in the heap of badly phrased questions it will be a pain to find anything relevant. I love writing documentation too, but from years participating on Stack Overflow I found it most unreliable for the purpose. As I once quipped, "Imagine Wikipedia where there ar…

> In a wiki, at least I can follow the structure to find relevant pages

Wow! You have much more disciplined coworkers than most of us, then. I've been at my current employer for about 13 years now. We've gone through 3 or 4 different wikis. Right now we're split between Confluence (worst wiki software I've ever used) and an in-house solution. I can't find a god damned thing on either one. They're both awful, and so were the predecessors. Maintaining any kind of documentation takes work and our employer just doesn't give us enough time to do that and our jobs.

Re: Stack Overflow for Teams

#144

Post by htaoerth29th »

tootie wrote: post #56
bluedino wrote: post #54

There's nothing like writing up an Evernote or Wiki article on some feature, process, or how/why something works... and then nobody on the team ever reading. I love writing documentation from time to time. But this helps by getting you to write documentation for only things people are asking about.

I think the win would be in making the answers more findable. Confluence is great for writing documents and laying out pages in a hierarchy, but full-text search is still very hit and miss. Especially when you have 50 projects that all have the same keywords and 49 of them are irrelevant.

> Confluence is great for writing documents

Citation needed. I use it almost daily and it's essentially write-only and pretty unusably so at that.

Re: Stack Overflow for Teams

#145

Post by 2trill2spill »

nugator wrote: post #104
dbingham wrote: post #72

Earlier quoted context omitted.

Pushing the need for clear documentation is a battle I find myself frequently fighting. Many devs just aren't sure how to prioritize it or write it, and even worse, many seem to have absorbed the idea that code should be self documenting and that comments are a code smell. Whoever is responsible for the idea that comments are code smell deserves to receive all future vitriolic emails from anyone who ever stumbles int…

Sorry to say that I'm one of those guys. I never comment code that is straightforward and easy to understand if I succeed with naming classes, methods and variables right. If I need to solve something in an illogical way due to other requirements/bugs that are out of my control I comment it. I have read to many comments stating the obvious or that are just plain wrong. No comments are better than comments with errors…

> Sorry to say that I'm one of those guys. I never comment code that is straightforward and easy to understand if I succeed with naming classes, methods and variables right. If I need to solve something in an illogical way due to other requirements/bugs that are out of my control I comment it.

I think that's fine. I only comment code that is not obvious, breaks common idioms used in the code base or stuff that seems stupid but is actually needed because of legacy code or systems.

Re: Stack Overflow for Teams

#146

Post by soneca »

jonhmchan wrote: post #77
soneca wrote: post #73

Earlier quoted context omitted.

"Documentation on-demand" seems a great solution indeed! Although $5/month per user is not cheap. I work at a medium-sized funded startup and I doubt it would be approved for overall use (as it would be nice to include other teams as well, like Marketing, Analytics, Customer Support). It is the same price of GSuite, that adds a ton more value than SO for Teams could ever add.

SO dev here. Not sure your size, but your first 10 users are much cheaper. On signup, it starts at $10/month and includes the first 10 users. It's $5/user/mo after that. If you're much larger than 10 - creeping into the 200+ people, it might be better to go with Enterprise: https://stackoverflow.com/enterprise

Thanks for commenting. We are 50 devs and it would be useful to have around more 50~100 in it.

I always have the impression that "Enterprise" plans are more expensive, but probably is just a misconception of mine.

Re: Stack Overflow for Teams

#147

Post by soneca »

chatmasta wrote: post #120
soneca wrote: post #73

Earlier quoted context omitted.

"Documentation on-demand" seems a great solution indeed! Although $5/month per user is not cheap. I work at a medium-sized funded startup and I doubt it would be approved for overall use (as it would be nice to include other teams as well, like Marketing, Analytics, Customer Support). It is the same price of GSuite, that adds a ton more value than SO for Teams could ever add.

I’m not sure I would want to work for a company that thinks spending an additional $5 is not worth improving my productivity. How much do you pay an engineer per year? You can’t afford an additional $5x12=$60, really? This argument would make a lot more sense if it was $500 per month per dev, which some SaaS companies actually do charge per-seat for enterprise licensing plans. A $5 per user per month charge is actual…

I think you just assumed a lot from a casual comment with no context.

Re: Stack Overflow for Teams

#148

Post by ci5er »

megaman22 wrote: post #32
tekkk wrote: post #4

My question is, is this better than your self-hosted wiki? At least that's cheaper and isn't a vendor lock-in. Sure wiki doesn't have the best possible UI and the UX might be too so-and-so. If I were in a position to buy this kind of service I'd still want something more out of it. Maybe if it offered a way to export Slack threads into SO as questions so they wouldn't get lost. Sure you could generate those questions…

Has there ever been a self-hosted wiki that was good? I'm only half joking - we've been through a few of them, and never found anything that was easy enough to use that people actually would. And thus everything gets shoved into email, and perpetually lost. I'm actually kind of excited about the idea of an internal StackOverflow. Of course, people would have to actually use it, and that battlefield is littered with t…

We used mailing list per topic (think channels) that anyone could subscribe to, and piper mail for searchable archives, and a $100 bounty for every relevant topic turned into a GFM document (with guidelines for minimal structure w.r.t. pros and cons and whats, whys and hows). Seemed to work. Of course this was before people discovered Slack, destroyer of institutional knowledge.

Re: Stack Overflow for Teams

#149

Post by Noumenon72 »

htaoerth29th wrote: post #143
colshrapnel wrote: post #61

Earlier quoted context omitted.

SO is bad with search, entirely giving it away for Google to find relevant answers. In a wiki, at least I can follow the structure to find relevant pages, but in the heap of badly phrased questions it will be a pain to find anything relevant. I love writing documentation too, but from years participating on Stack Overflow I found it most unreliable for the purpose. As I once quipped, "Imagine Wikipedia where there ar…

> In a wiki, at least I can follow the structure to find relevant pages Wow! You have much more disciplined coworkers than most of us, then. I've been at my current employer for about 13 years now. We've gone through 3 or 4 different wikis. Right now we're split between Confluence (worst wiki software I've ever used) and an in-house solution. I can't find a god damned thing on either one. They're both awful, and so w…

Confluence is one of the best designed products I've ever worked with. Makes the web behave like a native editor, awesome semantic macros that let you put in warnings or collapsible sections in a few keystrokes, you can generate page source with scripts.

Specifically regarding structure:

- every page has breadcrumbs letting you navigate up to its parents

- "child view" macro shows all children of this page automatically, so you can easily make a "category" page linking similar issues that is always up to date

- can move pages to new parents/spaces with a few clicks, or en masse with a drag-and-drop tree view

- built-in widget that searches only children of the page you embed it into

- spaces so you can tell a page in the search is owned by a different section of the team

Plus just a way lower barrier to entry than Wikipedia or the other wikis I've contributed to. I love Confluence.

Re: Stack Overflow for Teams

#150

Post by your-nanny »

chatmasta wrote: post #123
snarf21 wrote: post #121

Earlier quoted context omitted.

The conclusion I've come to in regards to comments is that each function should have a comment about WHY it is needed. As you said the code will change and exactly what it does will morph, but the why describes the architecture (somewhat) and hints at the abstraction model.

Please no, do not comment every function. Each function should average 5-10 lines, with clearly defined separation of concerns, and a descriptive name that inherently describes any writes/reads of the function. In the rare case where it makes sense to have a massive function, and you can’t break it into smaller functions within its scope, then maybe it makes sense to use a comment. Adopting a policy of commenting eve…

I agree, except i think you missed parents point, which was to document why the function was being written, not what the code _does_
Post reply on HN