bloomberg / bloomberg/ntf-core

Default settings are not documented and options stream operator is unhelpful

Open
#40 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
99
Forks
33
PR merge metrics
No merged PRs in 30d

Description

The documentation does not state what defaults are used by the various options. For example, in ntca_streamsocketoptions.h, there are numerous settings, but the doc doesn't say what each one is if I don't set it explicitly.

It would be nice to have the documentation complete for this (and quite a few other classes that do similar things). That way, I wouldn't have to read the code or write a test case to find out.

I got surprised by this when I noticed that, by default, Nagle is turned off. That's an unusual default, seeing that native default is to have Nagle turned on. Regardless of whether it makes sense to make this the default or not, if the documentation stated what the default is, I wouldn't have to guess.

I tried looking at the default by inserting the default options into a stream. This prints:
```
[ transport = UNDEFINED sourceEndpoint = NULL reuseAddress = false readQueueLowWatermark = NULL readQueueHighWatermark = NULL writeQueueLowWatermark = NULL writeQueueHighWatermark = NULL sendGreedily = NULL receiveGreedily = NULL sendBufferSize = NULL receiveBufferSize = NULL sendBufferLowWatermark = NULL receiveBufferLowWatermark = NULL sendTimeout = NULL receiveTimeout = NULL keepAlive = NULL noDelay = NULL debugFlag = NULL allowBroadcasting = NULL bypassNormalRouting = NULL leaveOutOfBandDataInline = NULL lingerFlag = NULL lingerTimeout = NULL keepHalfOpen = NULL metrics = NULL loadBalancingOptions = [ ] ]
```
This is not useful because I still can't see what settings are actually in effect.

Contributor guide

Open the contributing guide

Research direction

Start with ntca_streamsocketoptions.h and the default-options stream output included in the issue. Trace how each option's default is established, then document those defaults and clarify the stream representation so it reflects useful effective settings; done means readers no longer need to inspect code or write a test to determine defaults.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation, networking
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.