2
\$\begingroup\$

My upcoming KoTH, Fellowship, has a really large API.

Fundamentally, there are 5 classes the player needs to work with:

  • Player is the class they need to implement (6 functions)
  • ReadonlyCharacter is the class for each of the characters they control (25 functions)
  • ReadonlyAbility is the class for abilities characters can have (4 functions)
  • ReadonlyAction is the class for actions characters can have (7 functions)
  • ReadonlyTeam/EnemyTeam are classes for the teams the characters are on. (4 functions)

Some of these are less important (teams and abilities), but if my post is going to be self-contained, I would theoretically need to describe all of the functions I've listed above.

I've got a couple of options here:

  1. Only describe the critical parts in my post. Answer any questions in comments/chat.
  2. Describe everything. This would lead to a post with lots of information unimportant to most readers (and a really long post)
  3. Something else?

What should I do in my situation?

| |
\$\endgroup\$
  • \$\begingroup\$ Hi Nathan 👋 - I know this is an old question but how did this work out in the end? Were there any issues with working with an over-large interface? \$\endgroup\$ – AJFaraday Apr 5 at 20:57
  • \$\begingroup\$ I ended up describing the overall concepts, and just had a big code dump listing all of the individual functions: codegolf.stackexchange.com/questions/99744/… \$\endgroup\$ – Nathan Merrill Apr 6 at 3:41
  • \$\begingroup\$ Oh wow! You weren’t joking about that being a big API. I think I’d forgotten just how long CGC questions get. \$\endgroup\$ – AJFaraday Apr 6 at 7:01
3
\$\begingroup\$

Describe only the information about the public API that readers need to know

You don't have to go into detail about how every part of the public API is implemented - just a rough overview of the different classes and methods, and their uses.

For example, if you have a method that looks like this:

public UsefulInformation getInformation() {
    // 100 lines of code
}

It's fine to not include the // 100 lines of code, and just include the method signature and a brief comment describing the method:

// returns a UsefulInformation object containing the current game state
public UsefulInformation getInformation();

If anyone wants full implementation details, they can look at the full source code that you have hosted in a public location (like a public GitHub repository), via the link you include in the challenge body.

| |
\$\endgroup\$
  • \$\begingroup\$ "Need to know" is a bit unclear? There are lots of "informational" functions that readers who want to write a decently competitive bot will need to know. On the flipside, I can only explain the minimum number of functions that readers need to know to understand the post. \$\endgroup\$ – Nathan Merrill Oct 23 '16 at 1:22
  • \$\begingroup\$ @NathanMerrill Is that better? \$\endgroup\$ – Mego Oct 23 '16 at 1:46
  • \$\begingroup\$ To be clear, you are indicating that I should list all 46 public methods with a short description? If that's your intention, then, yes its clear :) \$\endgroup\$ – Nathan Merrill Oct 23 '16 at 1:50
  • \$\begingroup\$ @NathanMerrill Ideally, yes. If you run into post length issues, you may consider linking to a GitHub Gist or a README file in the repository for the explanations. Bonus points if you compress the explanations and include the base64-encoded compressed file. \$\endgroup\$ – Mego Oct 23 '16 at 1:52

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .