Как правильно откоментировать этот код?
Помогите пожалуйста грамотна откомментировать код
import xml.etree.ElementTree as XmlElementTree
import xml.etree.ElementTree as XmlElementTree
import httplib2
import uuid
#импорт нативных библиотек
from config import ***
#импорт конфига
***_HOST = '***'
***_PATH = '/***_xml'
CHUNK_SIZE = 1024 ** 2
#?
def speech_to_text(
filename=None,
bytes=None,
request_id=uuid.uuid4().hex,
topic='notes',
lang='ru-RU',
key=***_API_KEY):
if filename:
with open(filename, 'br') as file:
bytes = file.read()
if not bytes:
raise Exception('Neither file name nor bytes provided.')
bytes = convert_to_pcm16b16000r(in_bytes=bytes)
url = ***_PATH + '?uuid=%s&key=%s&topic=%s&lang=%s' % (
request_id,
key,
topic,
lang
)
#метод обработки файла
chunks = read_chunks(CHUNK_SIZE, bytes)
connection = httplib2.HTTPConnectionWithTimeout(***_HOST)
#подключение к страницы для передачи заголовка
connection.connect()
connection.putrequest('POST', url)
connection.putheader('Transfer-Encoding', 'chunked')
connection.putheader('Content-Type', 'audio/x-pcm;bit=16;rate=16000')
connection.endheaders()
for chunk in chunks:
connection.send(('%s\r\n' % hex(len(chunk))[2:]).encode())
connection.send(chunk)
connection.send('\r\n'.encode())
connection.send('0\r\n\r\n'.encode())
response = connection.getresponse()
#отправка и получение ответа
if response.code == 200:
response_text = response.read()
xml = XmlElementTree.fromstring(response_text)
#?
if int(xml.attrib['success']) == 1:
max_confidence = - float("inf")
text = ''
for child in xml:
if float(child.attrib['confidence']) > max_confidence:
text = child.text
max_confidence = float(child.attrib['confidence'])
if max_confidence != - float("inf"):
return text
else:
raise SpeechException('No text found.\n\nResponse:\n%s' % (response_text))
else:
raise SpeechException('No text found.\n\nResponse:\n%s' % (response_text))
else:
raise SpeechException('Unknown error.\nCode: %s\n\n%s' % (response.code, response.read()))
сlass SpeechException(Exception):
pass
Ответы (1 шт):
Автор решения: Roman Konoval
→ Ссылка
У вашего кода будет как минимум две категории пользователей:
- клиенты, которым все равно, что там внутри. Главное для них - знать как пользоваться этим API.
- программисты, которые будут поддерживать (и развивать) этот код.
Клиенты
В идеале для них важны ответы на такие вопросы:
- что эта функция делает?
- примеры использования
- какие параметры принимает?
- в каком формате должны быть параметры? Скажем, у аудио 100500 форматов, какие поддерживаются?
- какие ошибочные ситуации функции определяет? как на них реагирует?
- конфигурация: ключи, хосты, пароли - это от какого стороннего сервиса? Где из взять?
Тут docstring, который отвечает на эти вопросы был бы очень полезен.
Программисты
Их (в дополнение к вышеперечисленному) интересует:
- как функция устроена?
- как ее протестировать?
- как ее уже тестировали?
Тут большинство вещей по хорошему решаются не комментариями, но на худой конец можно и ими воспользоваться.