I was implementing functions to display a text file, using Python. One alternative is:

fn = ".\\my_data.txt"
show_lines(fn, 1, 4)   # first four lines
show_lines(fn, 3, 5)   # lines 3-5 inclusive
show_lines(fn, 7, 7)   # just line 7
show_lines(fn, 1, -1)  # show all lines
show_lines(fn, -1, 2)  # last two lines

In other words, there’s one meta show_lines() function where the parameters control the behavior. Another approach is:

show_first(fn, 4)       # first four lines
show_between(fn, 3, 5)  # lines 3-5
show_line(fn, 7)        # just line 7
show_all(fn)            # show all lines
show_last(fn, 2)        # last two lines

In other words, there are several dedicated functions. The dedicated function approach has two variations. Each function can be coded independently, or each function can be coded as a wrapper around the meta show_lines() function. For example:

def show_first(fn, n_lines):
  show_lines(fn, 1, n_lines)

There are pros and cons to each approach. An advantage of the one-meta-function approach is that users only have to remember, “to display a file I use the show_lines() function.” But users have to know magic parameters like -1 to mean all lines), and the implementation of the meta function will be quite complex.

The advantage of the dedicated-functions approach is that each function can be lean and relatively simple. The disadvantage is that users have to try and remember many more functions.

There are many other factors involved. For example, who will be using the library and for what purpose, error handling, and how frequently each function is likely to be used.

So, the bottom line is that there isn’t one best approach for code library API design.

An interesting human factor I’ve observed is that when a code library is being developed by a team of programmers, they’re inclined to always use the many dedicated functions approach. Engineers who are responsible for a code library want to show their boss that they’re making progress. It’s easier to say, “I implemented 20 functions in the Print library this month” than it is to say, “I implemented one elegant function in the Print library this month.”

Coin denominations have an interesting interface problem. In principle all you need is the 1-cent coin. But 5-cent, 10-cent, 25-cent coins are practical. Few people use 50-cent and one-dollar coins (especially the Susan B. Anthony and Sacagawea dollars, widely regarded by the people in forums at coinworld.com as two of the ugliest coins ever minted in the U.S.) The U.S. minted 2-cent coins from 1864-1872, 3-cent coins from 1865-1889, and 20-cent coins from 1875-1878. All three coins have attractive designs in my opinion. There was also a half-cent coin minted from 1793–1857.

# file_examine.py
# line_count(), column_count(), show_file(start,end),
# show_lines_with(), show_short_lines()

def line_count(fn, comment="#", has_header=False):
  fin = open(fn, "r")
  tot_lines = 0
  data_lines = 0
  for line in fin:
    tot_lines += 1
    if line.startswith(comment) == False:
      data_lines += 1
  if has_header == True:
    data_lines -= 1
  fin.close()
  return (tot_lines, data_lines)

def column_count(fn, line_num, delim):
  # number columns based on specified line
  fin = open(fn, "r")
  lst = list(fin)
  line = lst[line_num-1]
  tokens = line.split(delim)
  return len(tokens)

def show_file(fn, start, end, indices=False,
 strip_nl=False):
  fin = open(fn, "r")

  # advance to first line
  ln = 1
  while ln "less-than" start:
    fin.readline()
    ln += 1

  # show remaining lines
  while ln "less-equal" end:
    line = fin.readline()
    if line == "": break  # EOF
    if strip_nl == True:
      line = line.strip()
    if indices == True:
      print("[%3d]  " % ln, end="")
    print(line)
    ln += 1
  fin.close()

def show_all(fn, indices=False, strip_nl=False):
  fin = open(fn, "r")
  ln = 1
  for line in fin:
    if strip_nl == True:
      line = line.strip()
    if indices == True:
      print("[%3d]  " % ln, end="")
    print(line)
    ln += 1
  fin.close()

def show_last(fn, n, indices=False, strip_nl=False):
  tc, _ = line_count(fn)  # comments, header irrelevant
  start = tc - n + 1
  end = tc
  show_file(fn, start, end, indices, strip_nl)

# not useful for large files
# def show_line(fn, line_num):
#   fin = open(fn, "r")
#   lst = list(fin)
#   print(lst[line_num-1])
#   fin.close()  

def show_lines_with(fn, target_str):
  fin = open(fn, "r")
  line_num = 0
  for line in fin:
    line_num += 1
    if target_str in line:
      print("[%2d]:  " % line_num, end="")
      print(line)
  fin.close()

def show_short_lines(fn, num_cols, delim):
  fin = open(fn, "r")
  line_num = 0
  for line in fin:
    line_num += 1
    tokens = line.split(delim)
    if len(tokens) "less-than" num_cols:
      print("[%2d]:  " % line_num, end="")
      print(line)
  fin.close()  

# ==================

fn = ".\\people_raw.txt"
print("\nBegin examine " + fn)

print("\nTotal lines, data lines:")
(tc, dc) = line_count(fn, comment="#", has_header=True)
print(tc, dc)

print("\nAll lines: ")
show_all(fn, indices=True, strip_nl=True)

print("\nFirst 4 lines:")
show_file(fn, 1, 4, indices=True, strip_nl=True)

print("\nLines 4 - 6:")
show_file(fn, 4, 6, indices=True, strip_nl=True)

print("\nJust line 8:")
show_file(fn, 8, 8, indices=True, strip_nl=True)

print("\nLast 2 lines:")
show_last(fn, 2, indices=True, strip_nl=True)

print("\nNumber columns based on line 3:")
cc = column_count(fn, 3, '\t')
print(str(cc) + " columns")

print("\nLines with ? character:")
show_lines_with(fn, '?')

print("\nShort lines: ")
show_short_lines(fn, cc, '\t')

print("\nEnd examine")